[dd-trace] Improved GAC commands (#6995)

## Summary of changes

This PR improves the support in the GAC command, by allowing us to
install, uninstall and get info for multiple versions of an assembly.

## Reason for change

The current support only checks if an assembly is installed in the GAC
no matter version, causing an issue when a previous version of dd-trace
installed an old version of Datadog.Trace in the GAC meaning that we
bailout and don't install the new version, causing a crash when the
application loads.

<img width="1666" alt="image"
src="https://github.com/user-attachments/assets/f4a8b940-6718-470d-bc8c-0a6fc84bb838"
/>

## Implementation details

Now we include more unmanaged Fusion apis to list the version of the
assemblies installed in the GAC.

## Test coverage

Added a new `GacWithMultipleVersions` test.

## Other details
<!-- Fixes #{issue} -->

<!-- ⚠️ Note: where possible, please obtain 2 approvals prior to
merging. Unless CODEOWNERS specifies otherwise, for external teams it is
typically best to have one review from a team member, and one review
from apm-dotnet. Trivial changes do not require 2 reviews. -->

Author: tonyredondo

tracer/src/Datadog.Trace.Tools.Runner/Gac/AsmCacheFlags.cs

@@ -0,0 +1,15 @@
+// <copyright file="AsmCacheFlags.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+internal enum AsmCacheFlags
+{
+    ASM_CACHE_ZAP = 0x01,
+    ASM_CACHE_GAC = 0x02,
+    ASM_CACHE_DOWNLOAD = 0x04,
+    ASM_CACHE_ROOT = 0x08,
+    ASM_CACHE_ROOT_EX = 0x80
+}

tracer/src/Datadog.Trace.Tools.Runner/Gac/AsmDisplayFlags.cs

@@ -0,0 +1,22 @@
+// <copyright file="AsmDisplayFlags.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+internal enum AsmDisplayFlags
+{
+    ASM_DISPLAYF_VERSION = 0x1,
+    ASM_DISPLAYF_CULTURE = 0x2,
+    ASM_DISPLAYF_PUBLIC_KEY_TOKEN = 0x4,
+    ASM_DISPLAYF_PUBLIC_KEY = 0x8,
+    ASM_DISPLAYF_CUSTOM = 0x10,
+    ASM_DISPLAYF_PROCESSORARCHITECTURE = 0x20,
+    ASM_DISPLAYF_LANGUAGEID = 0x40,
+    ASM_DISPLAYF_RETARGET = 0x80,
+    ASM_DISPLAYF_CONFIG_MASK = 0x100,
+    ASM_DISPLAYF_MVID = 0x200,
+    ASM_DISPLAYF_CONTENT_TYPE = 0x400,
+    ASM_DISPLAYF_FULL = (((((ASM_DISPLAYF_VERSION | ASM_DISPLAYF_CULTURE) | ASM_DISPLAYF_PUBLIC_KEY_TOKEN) | ASM_DISPLAYF_RETARGET) | ASM_DISPLAYF_PROCESSORARCHITECTURE) | ASM_DISPLAYF_CONTENT_TYPE)
+}

tracer/src/Datadog.Trace.Tools.Runner/Gac/AssemblyCacheInstallFlags.cs

@@ -13,6 +13,15 @@ namespace Datadog.Trace.Tools.Runner.Gac;
 internal enum AssemblyCacheInstallFlags
 {
     None = 0x0,
+
+    /// <summary>
+    /// Replace existing files in the side-by-side store with the files in the assembly being installed
+    /// if the version of the file in the assembly is greater than or equal to the version of the existing file.
+    /// </summary>
     IASSEMBLYCACHE_INSTALL_FLAG_REFRESH = 0x1,
+
+    /// <summary>
+    /// Replace existing files in the side-by-side store with the files in the assembly being installed.
+    /// </summary>
     IASSEMBLYCACHE_INSTALL_FLAG_FORCE_REFRESH = 0x2,
 }

tracer/src/Datadog.Trace.Tools.Runner/Gac/CreateAsmNameObjFlags.cs

@@ -0,0 +1,25 @@
+// <copyright file="CreateAsmNameObjFlags.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+using System;
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+[Flags]
+internal enum CreateAsmNameObjFlags
+{
+    /// <summary>
+    /// If this flag is specified, the szAssemblyName parameter of CreateAssemblyNameObject is a fully-specified
+    /// side-by-side assembly name and is parsed to the individual properties.
+    /// </summary>
+    CANOF_PARSE_DISPLAY_NAME = 0x1,
+
+    /// <summary>
+    /// Reserved.
+    /// </summary>
+    CANOF_SET_DEFAULT_VALUES = 0x2,
+    CANOF_VERIFY_FRIEND_ASSEMBLYNAME = 0x4,
+    CANOF_PARSE_FRIEND_DISPLAY_NAME = (CANOF_PARSE_DISPLAY_NAME | CANOF_VERIFY_FRIEND_ASSEMBLYNAME)
+}

tracer/src/Datadog.Trace.Tools.Runner/Gac/GacNativeMethods.Impl.cs

@@ -0,0 +1,75 @@
+// <copyright file="GacNativeMethods.Impl.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Reflection;
+using System.Runtime.InteropServices;
+using System.Text;
+using Microsoft.Win32;
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+internal sealed partial class GacNativeMethods
+{
+    private delegate Hresult CreateAssemblyCacheDelegate(out IAssemblyCache ppAsmCache, IntPtr reserved);
+
+    private delegate Hresult CreateAssemblyNameObjectDelegate(out IAssemblyName ppAssemblyNameObj, [MarshalAs(UnmanagedType.LPWStr)] string szAssemblyName, CreateAsmNameObjFlags flags,  IntPtr pvReserved);
+
+    private delegate Hresult CreateAssemblyEnumDelegate(out IAssemblyEnum pEnum, IntPtr pUnkReserved, IAssemblyName pName, AsmCacheFlags dwFlags, IntPtr pvReserved);
+
+    internal IAssemblyCache CreateAssemblyCache()
+    {
+        var createAssemblyCachePointer = NativeLibrary.GetExport(GetPointer(), nameof(CreateAssemblyCache));
+        var createAssemblyCache = Marshal.GetDelegateForFunctionPointer<CreateAssemblyCacheDelegate>(createAssemblyCachePointer);
+        var hr = createAssemblyCache(out var ppAsmCache, IntPtr.Zero);
+        if (hr != Hresult.S_OK)
+        {
+            throw new TargetInvocationException($"Error creating AssemblyCache. HRESULT = {hr}", null);
+        }
+
+        return ppAsmCache;
+    }
+
+    internal IAssemblyName CreateAssemblyName(string assemblyName)
+    {
+        var createAssemblyNameObjectPointer = NativeLibrary.GetExport(GetPointer(), "CreateAssemblyNameObject");
+        var createAssemblyNameObject = Marshal.GetDelegateForFunctionPointer<CreateAssemblyNameObjectDelegate>(createAssemblyNameObjectPointer);
+        var hr = createAssemblyNameObject(out var ppAsmName, assemblyName, 0, IntPtr.Zero);
+        if (hr != Hresult.S_OK)
+        {
+            throw new TargetInvocationException($"Error creating AssemblyNameObject. HRESULT = {hr}", null);
+        }
+
+        return ppAsmName;
+    }
+
+    internal ICollection<AssemblyName> GetAssemblyNames(string assemblyName)
+    {
+        var createAssemblyEnumPointer = NativeLibrary.GetExport(GetPointer(), "CreateAssemblyEnum");
+        var createAssemblyEnum = Marshal.GetDelegateForFunctionPointer<CreateAssemblyEnumDelegate>(createAssemblyEnumPointer);
+        var pAssemblyName = CreateAssemblyName(assemblyName);
+        var hr = createAssemblyEnum(out var pAssemblyEnum, IntPtr.Zero, pAssemblyName, AsmCacheFlags.ASM_CACHE_GAC, IntPtr.Zero);
+        if (hr != Hresult.S_OK)
+        {
+            return [];
+        }
+
+        var lstAsmName = new List<AssemblyName>();
+        while (pAssemblyEnum.GetNextAssembly(IntPtr.Zero, out pAssemblyName, 0) == 0 && pAssemblyName != null)
+        {
+            var nSize = 260;
+            var sbDisplayName = new StringBuilder(nSize);
+            hr = pAssemblyName.GetDisplayName(sbDisplayName, ref nSize, AsmDisplayFlags.ASM_DISPLAYF_FULL);
+            if (hr == Hresult.S_OK)
+            {
+                lstAsmName.Add(new AssemblyName(sbDisplayName.ToString()));
+            }
+        }
+
+        return lstAsmName;
+    }
+}

….Trace.Tools.Runner/Gac/NativeMethods.cs …ace.Tools.Runner/Gac/GacNativeMethods.cstracer/src/Datadog.Trace.Tools.Runner/Gac/NativeMethods.cs renamed to tracer/src/Datadog.Trace.Tools.Runner/Gac/GacNativeMethods.cs tracer/src/Datadog.Trace.Tools.Runner/Gac/NativeMethods.cs renamed to tracer/src/Datadog.Trace.Tools.Runner/Gac/GacNativeMethods.cs

@@ -1,11 +1,10 @@
-// <copyright file="NativeMethods.cs" company="Datadog">
+// <copyright file="GacNativeMethods.cs" company="Datadog">
 // Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
 // This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
 // </copyright>
 
 using System;
 using System.IO;
-using System.Reflection;
 using System.Runtime.InteropServices;
 using System.Runtime.Versioning;
 using Microsoft.Win32;
@@ -16,13 +15,43 @@ namespace Datadog.Trace.Tools.Runner.Gac;
 #if NET5_0_OR_GREATER
 [SupportedOSPlatform("windows")]
 #endif
-internal sealed class NativeMethods
+internal sealed partial class GacNativeMethods : IDisposable
 {
     private const string NetFrameworkSubKey = @"SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\";
 
-    private delegate int CreateAssemblyCacheDelegate(out IAssemblyCache ppAsmCache, int reserved);
+    private IntPtr _libPointer;
 
-    internal static AssemblyCacheContainer CreateAssemblyCache()
+    private GacNativeMethods(IntPtr libPointer)
+    {
+        _libPointer = libPointer;
+    }
+
+    public static GacNativeMethods Create()
+    {
+        var fusionFullPath = GetFusionFullPath();
+        var lPointer = NativeLibrary.Load(fusionFullPath);
+
+        if (lPointer == IntPtr.Zero)
+        {
+            throw new Exception($"Error loading fusion library.");
+        }
+
+        return new GacNativeMethods(lPointer);
+    }
+
+    public void Dispose()
+    {
+        var lPointer = _libPointer;
+        if (lPointer == IntPtr.Zero)
+        {
+            return;
+        }
+
+        _libPointer = IntPtr.Zero;
+        NativeLibrary.Free(lPointer);
+    }
+
+    private static string GetFusionFullPath()
     {
         string fusionFullPath;
         using (var ndpKey = RegistryKey.OpenBaseKey(RegistryHive.LocalMachine, Environment.Is64BitProcess ? RegistryView.Registry64 : RegistryView.Registry32).OpenSubKey(NetFrameworkSubKey))
@@ -41,16 +70,17 @@ internal static AssemblyCacheContainer CreateAssemblyCache()
             throw new FileNotFoundException($"{fusionFullPath} cannot be found.");
         }
 
-        var libPointer = NativeLibrary.Load(fusionFullPath);
-        var createAssemblyCachePointer = NativeLibrary.GetExport(libPointer, nameof(CreateAssemblyCache));
-        var createAssemblyCache = Marshal.GetDelegateForFunctionPointer<CreateAssemblyCacheDelegate>(createAssemblyCachePointer);
-        var hr = createAssemblyCache(out var ppAsmCache, 0);
-        if (hr != 0)
+        return fusionFullPath;
+    }
+
+    private IntPtr GetPointer()
+    {
+        var lPointer = _libPointer;
+        if (lPointer == IntPtr.Zero)
         {
-            NativeLibrary.Free(libPointer);
-            throw new TargetInvocationException($"Error creating AssemblyCache. HRESULT = {hr}", null);
+            throw new Exception("Fusion library has not been loaded.");
         }
 
-        return new AssemblyCacheContainer(libPointer, ppAsmCache);
+        return lPointer;
     }
 }

tracer/src/Datadog.Trace.Tools.Runner/Gac/Hresult.cs

@@ -0,0 +1,80 @@
+// <copyright file="Hresult.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+internal enum Hresult : int
+{
+    /// <summary>
+    /// Operation successful
+    /// </summary>
+    S_OK = 0,
+    S_FALSE = 1,
+
+    /// <summary>
+    /// Not implemented
+    /// </summary>
+    E_NOTIMPL = unchecked((int)0x80004001),
+
+    /// <summary>
+    /// No such interface supported
+    /// </summary>
+    E_NOINTERFACE = unchecked((int)0x80004002),
+
+    /// <summary>
+    /// Pointer that is not valid
+    /// </summary>
+    E_POINTER = unchecked((int)0x80004003),
+
+    /// <summary>
+    /// Operation aborted
+    /// </summary>
+    E_ABORT = unchecked((int)0x80004004),
+
+    /// <summary>
+    /// Unspecified failure
+    /// </summary>
+    E_FAIL = unchecked((int)0x80004005),
+
+    /// <summary>
+    /// Unexpected failure
+    /// </summary>
+    E_UNEXPECTED = unchecked((int)0x8000FFFF),
+
+    /// <summary>
+    /// File not found error
+    /// </summary>
+    E_FILENOTFOUND = unchecked((int)0x80070002),
+
+    /// <summary>
+    /// General access denied error
+    /// </summary>
+    E_ACCESSDENIED = unchecked((int)0x80070005),
+
+    /// <summary>
+    /// Handle that is not valid
+    /// </summary>
+    E_HANDLE = unchecked((int)0x80070006),
+
+    /// <summary>
+    /// Failed to allocate necessary memory
+    /// </summary>
+    E_OUTOFMEMORY = unchecked((int)0x8007000E),
+
+    /// <summary>
+    /// One or more arguments are not valid
+    /// </summary>
+    E_INVALIDARG = unchecked((int)0x80070057),
+
+    /// <summary>
+    /// Strong name signature could not be verified. The assembly may have been tampered with, or it was delay signed but not fully signed with the correct private key.
+    /// </summary>
+    E_INVALIDSTRONGNAME = unchecked((int)0x80131045),
+
+    /// <summary>
+    /// The given assembly name or codebase was invalid.
+    /// </summary>
+    E_INVALIDASSEMBLY = unchecked((int)0x80131047)
+}

tracer/src/Datadog.Trace.Tools.Runner/Gac/HresultHelper.cs

@@ -0,0 +1,24 @@
+// <copyright file="HresultHelper.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+internal static class HresultHelper
+{
+    public static string ToStringOrHex(this Hresult hresult)
+    {
+        var str = hresult.ToString();
+        if (int.TryParse(str, out _))
+        {
+            str = $"0x{((int)hresult):x8}";
+        }
+        else
+        {
+            str += $" [0x{(int)hresult:x8}]";
+        }
+
+        return str;
+    }
+}

tracer/src/Datadog.Trace.Tools.Runner/Gac/IAssemblyCache.cs

@@ -16,17 +16,17 @@ namespace Datadog.Trace.Tools.Runner.Gac;
 internal interface IAssemblyCache
 {
     [PreserveSig]
-    int UninstallAssembly(UninstallAssemblyFlags dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pszAssemblyName, IntPtr pvReserved, out UninstallDisposition pulDisposition);
+    Hresult UninstallAssembly(UninstallAssemblyFlags dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pszAssemblyName, IntPtr pvReserved, out UninstallDisposition pulDisposition);
 
     [PreserveSig]
-    int QueryAssemblyInfo(QueryAssemblyInfoFlag dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pszAssemblyName, ref AssemblyInfo pAsmInfo);
+    Hresult QueryAssemblyInfo(QueryAssemblyInfoFlag dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pszAssemblyName, ref AssemblyInfo pAsmInfo);
 
     [PreserveSig]
-    int CreateAssemblyCacheItem(uint dwFlags, IntPtr pvReserved, out IAssemblyCacheItem ppAsmItem, [MarshalAs(UnmanagedType.LPWStr)] string pszAssemblyName);
+    Hresult CreateAssemblyCacheItem(uint dwFlags, IntPtr pvReserved, out IAssemblyCacheItem ppAsmItem, [MarshalAs(UnmanagedType.LPWStr)] string pszAssemblyName);
 
     [PreserveSig]
-    int CreateAssemblyScavenger(out object ppAsmScavenger);
+    Hresult CreateAssemblyScavenger(out object ppAsmScavenger);
 
     [PreserveSig]
-    int InstallAssembly(AssemblyCacheInstallFlags dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pszManifestFilePath, IntPtr pvReserved);
+    Hresult InstallAssembly(AssemblyCacheInstallFlags dwFlags, [MarshalAs(UnmanagedType.LPWStr)] string pszManifestFilePath, IntPtr pvReserved);
 }

tracer/src/Datadog.Trace.Tools.Runner/Gac/IAssemblyEnum.cs

@@ -0,0 +1,20 @@
+// <copyright file="IAssemblyEnum.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+using System;
+using System.Runtime.InteropServices;
+
+namespace Datadog.Trace.Tools.Runner.Gac;
+
+[Guid("21b8916c-f28e-11d2-a473-00c04f8ef448")]
+[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+internal interface IAssemblyEnum
+{
+    Hresult GetNextAssembly(IntPtr pvReserved, out IAssemblyName ppName, int dwFlags);
+
+    Hresult Reset();
+
+    Hresult Clone(out IAssemblyEnum ppEnum);
+}