The native code application programming interfaces (APIs)
that allow you to interact with the Global Assembly Cache (GAC) are not
documented in the .NET Framework Software Development Kit (SDK) documentation.
CAUTION: Do not use these APIs in your application to perform assembly
binds or to test for the presence of assemblies or other run time, development,
or design-time operations. Only administrative tools and setup programs must
use these APIs. If you use the GAC, this directly exposes your application to
assembly binding fragility or may cause your application to work improperly on
future versions of the .NET Framework.
The GAC stores assemblies that
are shared across all applications on a computer. The actual storage location
and structure of the GAC is not documented and is subject to change in future
versions of the .NET Framework and the Microsoft Windows operating
The only supported method to access assemblies in the GAC is
through the APIs that are documented in this article.
applications do not have to use these APIs because the assembly binding is
performed automatically by the common language runtime. Only custom setup
programs or management tools must use these APIs. Microsoft Windows Installer
has native support for installing assemblies to the GAC.
information about assemblies and the GAC, see the .NET Framework SDK.
Use the GAC API in the following scenarios:
When you install an assembly to the GAC.
When you remove an assembly from the GAC.
When you export an assembly from the GAC.
When you enumerate assemblies that are available in the
NOTE: CoInitialize(Ex) must be called before you use any of the functions and interfaces
that are described in this specification.
The IAssemblyCache interface is the top-level interface that provides access to the
To obtain an instance of the CreateAssemblyCache API, call the CreateAssemblyCache API, as follows:
The FUSION_INSTALL_REFERENCE structure represents a reference that is made when an application
has installed an assembly in the GAC.
typedef struct _FUSION_INSTALL_REFERENCE_
GUID guidScheme; // Contains one of the pre-defined GUIDs.
LPCWSTR szIdentifier; // Unique identifier for the application that installs this assembly.
LPCWSTR szNonCannonicalData; // Data is description; relevant to the GUID above.
} FUSION_INSTALL_REFERENCE, *LPFUSION_INSTALL_REFERENCE;
The fields of the structure are defined as follows:
cbSize - The size of the structure in bytes.
dwFlags - Reserved, must be zero.
guidScheme - The entity that adds the reference.
szIdentifier - A unique string that identifies the application that installed
szNonCannonicalData - A string that is only understood by the entity that adds the
reference. The GAC only stores this string.
Possible values for the guidScheme field can be one of the following:
FUSION_REFCOUNT_MSI_GUID - The assembly is referenced by an application that has been
installed by using Windows Installer. The szIdentifier field is set to MSI, and szNonCannonicalData is set to Windows Installer. This scheme must only be used by Windows Installer
FUSION_REFCOUNT_UNINSTALL_SUBKEY_GUID - The assembly is referenced by an application that appears in Add/Remove Programs. The szIdentifier field is the token that is used to register the application with Add/Remove programs.
FUSION_REFCOUNT_FILEPATH_GUID - The assembly is referenced by an application that is
represented by a file in the file system. The szIdentifier field is the path to this file.
FUSION_REFCOUNT_OPAQUE_STRING_GUID - The assembly is referenced by an application that is only
represented by an opaque string. The szIdentifier is this opaque string. The GAC does not perform existence
checking for opaque references when you remove this.
The ASSEMBLY_INFO structure represents information about an assembly in the
The fields of the structure are defined as follows:
cbAssemblyInfo - Size of the structure in bytes. Permits additions to the
structure in future version of the .NET Framework.
dwAssemblyFlags - Indicates one or more of the ASSEMBLYINFO_FLAG_* bits.
uliAssemblySizeInKB - The size of the files that make up the assembly in kilobytes
pszCurrentAssemblyPathBuf - A pointer to a string buffer that holds the current path of the
directory that contains the files that make up the assembly. The path must end
with a zero.
cchBuf - Size of the buffer that the pszCurrentAssemblyPathBug field points to.
dwAssemblyFlags can have one of the following values:
ASSEMBLYINFO_FLAG__INSTALLED - Indicates that the assembly is actually installed. Always set
in current version of the .NET Framework.
ASSEMBLYINFO_FLAG__PAYLOADRESIDENT - Never set in the current version of the .NET
The IAssemblyCache::UninstallAssembly method removes a reference to an assembly from the GAC. If other
applications hold no other references to the assembly, the files that make up
the assembly are removed from the GAC.
pszAssemblyName - The name of the assembly. A zero-ended Unicode
pRefData - A pointer to a FUSION_INSTALL_REFERENCE structure. Although this is not recommended, this parameter can
be null. The assembly is installed without an application reference, or all
existing application references are gone.
pulDisposition - Pointer to an integer that indicates the action that is
performed by the function.
NOTE: If pulDisposition is not null, pulDisposition contains one of the following values:
IASSEMBLYCACHE_UNINSTALL_DISPOSITION_UNINSTALLED - The assembly files have been removed from the GAC.
IASSEMBLYCACHE_UNINSTALL_DISPOSITION_STILL_IN_USE - An application is using the assembly. This value is returned on
Microsoft Windows 95 and Microsoft Windows 98.
IASSEMBLYCACHE_UNINSTALL_DISPOSITION_ALREADY_UNINSTALLED - The assembly does not exist in the GAC.
IASSEMBLYCACHE_UNINSTALL_DISPOSITION_DELETE_PENDING - Not used.
IASSEMBLYCACHE_UNINSTALL_DISPOSITION_HAS_INSTALL_REFERENCES - The assembly has not been removed from the GAC because another
application reference exists.
IASSEMBLYCACHE_UNINSTALL_DISPOSITION_REFERENCE_NOT_FOUND - The reference that is specified in pRefData is not found in the GAC.
The return values are defined as follows:
S_OK - The assembly has been uninstalled.
S_FALSE - The operation succeeded, but the assembly was not removed from
the GAC. The reason is described in pulDisposition.
The IAssemblyCache::QueryAssemblyInfo method retrieves information about an assembly from the GAC.
dwFlags - One of QUERYASMINFO_FLAG_VALIDATE or QUERYASMINFO_FLAG_GETSIZE:
*_VALIDATE - Performs validation of the files in the GAC against the
assembly manifest, including hash verification and strong name signature
*_GETSIZE - Returns the size of all files in the assembly (disk footprint).
If this is not specified, the ASSEMBLY_INFO::uliAssemblySizeInKB field is not modified.
pszAssemblyName - Name of the assembly that is queried.
pAsmInfo - Pointer to the returned ASSEMBLY_INFO structure.
The IAssemblyCache::InstallAssembly method adds a new assembly to the GAC. The assembly must be
persisted in the file system and is copied to the GAC.
HRESULT InstallAssembly( // If you use this, fusion will do the streaming & commit.
[in] DWORD dwFlags,
[in] LPCWSTR pszManifestFilePath,
[in] LPCFUSION_INSTALL_REFERENCE pRefData
The parameters are defined as follows:
dwFlags - At most, one of the bits of the IASSEMBLYCACHE_INSTALL_FLAG_* values can be specified:
*_REFRESH - If the assembly is already installed in the GAC and the file
version numbers of the assembly being installed are the same or later, the
files are replaced.
*_FORCE_REFRESH - The files of an existing assembly are overwritten regardless of
their version number.
pszManifestFilePath - A string pointing to the dynamic-linked library (DLL) that
contains the assembly manifest. Other assembly files must reside in the same
directory as the DLL that contains the assembly manifest.
pRefData - A pointer to a FUSION_INSTALL_REFERENCE that indicates the application on whose behalf the assembly is
being installed. Although this is not recommended, this parameter can be null,
but this leaves the assembly without any application reference.
The IAssemblyName interface represents an assembly name. An assembly name includes
a predetermined set of name-value pairs. The assembly name is described in
detail in the .NET Framework SDK.
ppAssemblyNameObj - Pointer to a memory location that receives the IAssemblyName pointer that is created.
szAssemblyName - A string representation of the assembly name or of a full
assembly reference that is determined by dwFlags. The string representation can be null.
dwFlags - Zero or more of the bits that are defined in the CREATE_ASM_NAME_OBJ_FLAGS enumeration.
pvReserved - Must be null.
The CREATE_ASM_NAME_OBJ_FLAGS enumeration contains the following values:
CANOF_PARSE_DISPLAY_NAME - If this flag is specified, the szAssemblyName parameter is a full assembly name and is parsed to the individual
properties. If the flag is not specified, szAssemblyName is the "Name" portion of the assembly name.
CANOF_SET_DEFAULT_VALUES - If this flag is specified, certain properties, such as
processor architecture, are set to their default values.
ppRefData - A pointer to a FUSION_INSTALL_REFERENCE structure. The memory is allocated by the GetReference method and is freed when IInstallReferenceItem is released. Callers must not hold a reference to this buffer
after the IInstallReferenceItem object is released.
dwFlags - Must be zero.
pvReserved - Must be null.
The IInstallReferenceEnum interface enumerates all references that are set on an assembly
in the GAC.
NOTE: References that belong to the assembly are locked for changes
while those references are being enumerated.