DOC: Global Assembly Cache (GAC) APIs Are Not Documented in the .NET Framework Software Development Kit (SDK) Documentation (317540)

MORE INFORMATION

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 system.

The only supported method to access assemblies in the GAC is through the APIs that are documented in this article.

Most 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.

For more 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 GAC.

NOTE: CoInitialize(Ex) must be called before you use any of the functions and interfaces that are described in this specification.

IAssemblyCache Interface

The IAssemblyCache interface is the top-level interface that provides access to the GAC.

To obtain an instance of the CreateAssemblyCache API, call the CreateAssemblyCache API, as follows:

STDAPI CreateAssemblyCache(IAssemblyCache **ppAsmCache, DWORD dwReserved);

The parameters are defined as follows:

ppAsmCache - Pointer to return IAssemblyCache
dwReserved

FUSION_INSTALL_REFERENCE Structure

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_
    {
        DWORD  cbSize;
        DWORD  dwFlags;
        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 the assembly.
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 itself.
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.

ASSEMBLY_INFO Structure

The ASSEMBLY_INFO structure represents information about an assembly in the assembly cache.

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 (KB).
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 Framework.

IAssemblyCache::UninstallAssembly Method

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.

    HRESULT UninstallAssembly(
        [in] DWORD dwFlags,
        [in] LPCWSTR pszAssemblyName, 
        [in] LPCFUSION_INSTALL_REFERENCE pRefData, 
        [out, optional] ULONG *pulDisposition
        );

The parameters are defined as follows:

dwFlags - No flags defined. Must be zero.
pszAssemblyName - The name of the assembly. A zero-ended Unicode string.
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.

IAssemblyCache::QueryAssemblyInfo Method

The IAssemblyCache::QueryAssemblyInfo method retrieves information about an assembly from the GAC.

    HRESULT QueryAssemblyInfo(
        [in] DWORD dwFlags,
        [in] LPCWSTR pszAssemblyName,
        [in, out] ASSEMBLY_INFO *pAsmInfo
        );

The parameters are defined as follows:

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 verification.
- *_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.

IAssemblyCache::InstallAssembly Method

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.

IAssemblyName Interface

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.

[
        local,
        object,
        uuid(CD193BC0-B4BC-11d2-9833-00C04FC31D2E),
        pointer_default(unique)
]
interface IAssemblyName: IUnknown

An instance of IAssemblyName is obtained by calling the CreateAssemblyNameObject API:

STDAPI CreateAssemblyNameObject(LPASSEMBLYNAME *ppAssemblyNameObj, LPCWSTR szAssemblyName, DWORD dwFlags, LPVOID pvReserved);

The parameters are defined as follows:

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.

CREATE_ASM_NAME_OBJ_FLAGS Enumeration

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.

    typedef enum {
         CANOF_PARSE_DISPLAY_NAME = 0x1,
         CANOF_SET_DEFAULT_VALUES = 0x2
    } CREATE_ASM_NAME_OBJ_FLAGS;

ASM_NAME Enumeration

The ASM_NAME enumeration property ID describes the valid names of the name-value pairs in an assembly name. See the .NET Framework SDK for a description of these properties.

    typedef enum
    {
        ASM_NAME_PUBLIC_KEY = 0,
        ASM_NAME_PUBLIC_KEY_TOKEN,
        ASM_NAME_HASH_VALUE,
        ASM_NAME_NAME,
        ASM_NAME_MAJOR_VERSION,
        ASM_NAME_MINOR_VERSION,
        ASM_NAME_BUILD_NUMBER,
        ASM_NAME_REVISION_NUMBER,
        ASM_NAME_CULTURE,
        ASM_NAME_PROCESSOR_ID_ARRAY,
        ASM_NAME_OSINFO_ARRAY,
        ASM_NAME_HASH_ALGID,
        ASM_NAME_ALIAS,
        ASM_NAME_CODEBASE_URL,
        ASM_NAME_CODEBASE_LASTMOD,
        ASM_NAME_NULL_PUBLIC_KEY,
        ASM_NAME_NULL_PUBLIC_KEY_TOKEN,
        ASM_NAME_CUSTOM,
        ASM_NAME_NULL_CUSTOM,                
        ASM_NAME_MVID,
        ASM_NAME_MAX_PARAMS
    } ASM_NAME;

IAssemblyName::SetProperty Method

The IAssemblyName::SetProperty method adds a name-value pair to the assembly name, or, if a name-value pair with the same name already exists, modifies or deletes the value of a name-value pair.

    HRESULT SetProperty(
        [in]    DWORD  PropertyId, 
        [in]    LPVOID pvProperty,
        [in]    DWORD  cbProperty);

The parameters are defined as follows:

PropertyId - The ID that represents the name part of the name-value pair that is to be added or to be modified. Valid property IDs are defined in the ASM_NAME enumeration.
pvProperty - A pointer to a buffer that contains the value of the property.
cbProperty - The length of the pvProperty buffer in bytes. If cbProperty is zero, the name-value pair is removed from the assembly name.

IAssemblyName::GetProperty Method

The IAssemblyName::GetProperty method retrieves the value of a name-value pair in the assembly name that specifies the name.

    HRESULT GetProperty(
        [in]         DWORD    PropertyId, 
        [out]        LPVOID   pvProperty,
        [in, out]    LPDWORD  pcbProperty);

The parameters are defined as follows:

PropertyId - The ID that represents the name of the name-value pair whose value is to be retrieved. Specified property IDs are defined in the ASM_NAME enumeration.
pvProperty - A pointer to a buffer that is to contain the value of the property.
cbProperty - The length of the pvProperty buffer, in bytes.

IAssemblyName::Finalize Method

The IAssemblyName::Finalize method freezes an assembly name. Additional calls to IAssemblyName::SetProperty are unsuccessful after this method has been called.

HRESULT Finalize();

IAssemblyName::GetDisplayName Method

The IAssemblyName::GetDisplayName method returns a string representation of the assembly name.

    HRESULT  GetDisplayName(
        [out]       LPOLESTR  szDisplayName,
        [in, out]   LPDWORD   pccDisplayName,
        [in]        DWORD     dwDisplayFlags);

The parameters are defined as follows:

szDisplayName - A pointer to a buffer that is to contain the display name. The display name is returned in Unicode.
pccDisplayName - The size of the buffer in characters (on input). The length of the returned display name (on return).
dwDisplayFlags - One or more of the bits defined in the ASM_DISPLAY_FLAGS enumeration:
- *_VERSION - Includes the version number as part of the display name.
- *_CULTURE - Includes the culture.
- *_PUBLIC_KEY_TOKEN - Includes the public key token.
- *_PUBLIC_KEY - Includes the public key.
- *_CUSTOM - Includes the custom part of the assembly name.
- *_PROCESSORARCHITECTURE - Includes the processor architecture.
- *_LANGUAGEID - Includes the language ID.

    typedef enum
    {
        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_DISPLAY_FLAGS;

IAssemblyName::GetName Method

The IAssemblyName::GetName method returns the name part of the assembly name.

    HRESULT GetName(
        [in, out] LPDWORD lpcwBuffer,
        [out] WCHAR *pwzName);

The parameters are defined as follows:

lpcwBuffer - Size of the pwszName buffer (on input). Length of the name (on return).
pwszName - Pointer to the buffer that is to contain the name part of the assembly name.

IAssemblyName::GetVersion Method

The IAssemblyName::GetVersion method returns the version part of the assembly name.

HRESULT GetVersion(
        [out] LPDWORD pdwVersionHi,
        [out] LPDWORD pdwVersionLow);

The parameters are defined as follows:

pdwVersionHi - Pointer to a DWORD that contains the upper 32 bits of the version number.
pdwVersionLow - Pointer to a DWORD that contain the lower 32 bits of the version number.

IAssemblyName::IsEqual Method

The IAssemblyName::IsEqual method compares the assembly name to another assembly names.

    HRESULT IsEqual(
        [in] IAssemblyName *pName,
        [in] DWORD dwCmpFlags);

The parameters are defined as follows:

pName - The assembly name to compare to.
dwCmpFlags - Indicates which part of the assembly name to use in the comparison.

Values are one or more of the bits defined in the ASM_CMP_FLAGS enumeration:

    typedef enum
    {
        ASM_CMPF_NAME            = 0x1,
        ASM_CMPF_MAJOR_VERSION   = 0x2,
        ASM_CMPF_MINOR_VERSION   = 0x4,
        ASM_CMPF_BUILD_NUMBER    = 0x8,
        ASM_CMPF_REVISION_NUMBER = 0x10,
        ASM_CMPF_PUBLIC_KEY_TOKEN = 0x20,
        ASM_CMPF_CULTURE         = 0x40,
        ASM_CMPF_CUSTOM          = 0x80,
        ASM_CMPF_ALL = ASM_CMPF_NAME | ASM_CMPF_MAJOR_VERSION | ASM_CMPF_MINOR_VERSION |
                       ASM_CMPF_REVISION_NUMBER | ASM_CMPF_BUILD_NUMBER |
                       ASM_CMPF_PUBLIC_KEY_TOKEN | ASM_CMPF_CULTURE | ASM_CMPF_CUSTOM,
        // For strongly named assemblies, ASM_CMPF_DEFAULT==ASM_CMPF_ALL.
        // For simply named assemblies, this is also true. However, when
        // performing IAssemblyName::IsEqual, the build number/revision 
        // number will be removed from the comparison.
        ASM_CMPF_DEFAULT = 0x100
    } ASM_CMP_FLAGS;

The return values are as follows:

S_OK: - The names match according to the comparison criteria.
S_FALSE: - The names do not match.

IAssemblyName::Clone Method

The IAssemblyName::Clone method creates a copy of an assembly name.

    HRESULT Clone(
        [out] IAssemblyName **pName);

IAssemblyEnum Interface

The IAssemblyEnum interface enumerates the assemblies in the GAC.

 [
        local,
        object,
        uuid(21b8916c-f28e-11d2-a473-00c04f8ef448),
        pointer_default(unique)
]
interface IAssemblyEnum : IUnknown

To obtain an instance of the CreateAssemblyEnum API, call the CreateAssemblyNameObject API, as follows:

STDAPI CreateAssemblyEnum(IAssemblyEnum **pEnum, IUnknown *pUnkReserved, IAssemblyName *pName, DWORD dwFlags, LPVOID pvReserved);

The parameters are defined as follows:

pEnum - Pointer to a memory location that contains the IAssemblyEnum pointer.
pUnkReserved - Must be null.
pName - An assembly name that is used to filter the enumeration. Can be null to enumerate all assemblies in the GAC.
dwFlags - Exactly one bit from the ASM_CACHE_FLAGS enumeration.
pvReserved - Must be NULL.

ASM_CACHE_FLAGS Enumeration

The ASM_CACHE_FLAGS enumeration contains the following values:

ASM_CACHE_ZAP - Enumerates the cache of precompiled assemblies by using Ngen.exe.
ASM_CACHE_GAC - Enumerates the GAC.
ASM_CACHE_DOWNLOAD - Enumerates the assemblies that have been downloaded on-demand or that have been shadow-copied.

IAssemblyName::GetDisplayName

typedef enum
{
    ASM_CACHE_ZAP            = 0x1,
    ASM_CACHE_GAC            = 0x2,
    ASM_CACHE_DOWNLOAD       = 0x4
} ASM_CACHE_FLAGS;

IAssemblyEnum::GetNextAssembly Method

The IAssemblyEnum::GetNextAssembly method enumerates the assemblies in the GAC.

    HRESULT GetNextAssembly
    (
        [in]                  LPVOID                pvReserved,
        [out]                 IAssemblyName       **ppName,
        [in]                  DWORD                 dwFlags
    );

The parameters are defined as follows:

pvReserved - Must be null.
ppName - Pointer to a memory location that is to receive the interface pointer to the assembly name of the next assembly that is enumerated.
dwFlags - Must be zero.

IInstallReferenceItem Interface

The IInstallReferenceItem interface represents a reference that has been set on an assembly in the GAC. Instances of IInstallReferenceIteam are returned by the IInstallReferenceEnum interface.

[
        local,
        object,
        uuid(582dac66-e678-449f-aba6-6faaec8a9394),
        pointer_default(unique)
]
interface IInstallReferenceItem : IUnknown

IInstallReferenceItem::GetReference Method

The IInstallReferenceItem::GetReference method returns a FUSION_INSTALL_REFERENCE structure.

    HRESULT GetReference
    (
    [out] LPFUSION_INSTALL_REFERENCE *ppRefData,
    [in]  DWORD dwFlags,
    [in]  LPVOID pvReserved
    );

The parameters are defined as follows:

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.

IInstallReferenceEnum Interface

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.

[
        local,
        object,
        uuid(56b1a988-7c0c-4aa2-8639-c3eb5a90226f),
        pointer_default(unique)
]
interface IInstallReferenceEnum : IUnknown

To obtain an instance of the CreateInstallReferenceEnum API, call the CreateInstallReferenceEnum API, as follows:

STDAPI CreateInstallReferenceEnum(IInstallReferenceEnum **ppRefEnum, IAssemblyName *pName, DWORD dwFlags, LPVOID pvReserved);

The parameters are defined as follows:

ppRefEnum - A pointer to a memory location that receives the IInstallReferenceEnum pointer.
pName - The assembly name for which the references are enumerated.
dwFlags - Must be zero.
pvReserved - Must be null.

IInstallReferenceEnum::GetNextInstallReferenceItem Method

IInstallReferenceEnum::GetNextInstallReferenceItem returns the next reference information for an assembly.

    HRESULT GetNextInstallReferenceItem
            (
            [out] IInstallReferenceItem **ppRefItem,
            [in]  DWORD dwFlags,
            [in]  LPVOID pvReserved
            );

The parameters are defined as follows:

ppRefItem - Pointer to a memory location that receives the IInstallReferenceItem pointer.
dwFlags - Must be zero.
pvReserved - Must be null.

Return values are as follows:

S_OK: - The next item is returned successfully.
S_FALSE: - No more items.

GetCachePath API

The GetCachePath API returns the storage location of the GAC.

STDAPI GetCachePath(ASM_CACHE_FLAGS dwCacheFlags, LPWSTR pwzCachePath, PDWORD pcchPath);

The parameters are defined as follows:

dwCacheFlags - Exactly one of the bits defined in the ASM_CACHE_FLAGS enumeration.
pwzCachePath - Pointer to a buffer that is to receive the path of the GAC as a Unicode string.
pcchPath - Length of the pwszCachePath buffer, in Unicode characters.

// ==++==
// 
//   Copyright (c) Microsoft Corporation.  All rights reserved.
// 
// ==--==
//+---------------------------------------------------------------------------
// 
//  Microsoft Windows
//  File:       fusion.idl
// 
//  Contents:   Fusion Interfaces
// 
//  Classes:
// 
//  Functions:
// 
// 
//----------------------------------------------------------------------------
cpp_quote("//=--------------------------------------------------------------------------=")
cpp_quote("// fusion.h")
cpp_quote("//=--------------------------------------------------------------------------=")
cpp_quote("// Copyright (c) Microsoft Corporation.  All rights reserved.")
cpp_quote("//")
cpp_quote("// THIS CODE AND INFORMATION IS PROVIDED \"AS IS\" WITHOUT WARRANTY OF")
cpp_quote("// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO")
cpp_quote("// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A")
cpp_quote("// PARTICULAR PURPOSE.")
cpp_quote("//=--------------------------------------------------------------------------=")
cpp_quote("")
cpp_quote("#ifdef _MSC_VER")
cpp_quote("#pragma comment(lib,\"uuid.lib\")")
cpp_quote("#endif")
cpp_quote("")
cpp_quote("//---------------------------------------------------------------------------=")
cpp_quote("// Fusion Interfaces.")
cpp_quote("")

import "objidl.idl";

cpp_quote("#ifdef _MSC_VER")
cpp_quote("#pragma once")
cpp_quote("#endif")

interface IAssemblyCache;
interface IAssemblyCacheItem;
interface IAssemblyName;
interface IAssemblyEnum;


typedef enum
{
    ASM_CACHE_ZAP            = 0x1,
    ASM_CACHE_GAC            = 0x2,
    ASM_CACHE_DOWNLOAD       = 0x4
} ASM_CACHE_FLAGS;

/////////////////////////////////////////////////////////////////////////////// 
// 
// IAssemblyCache
// 
/////////////////////////////////////////////////////////////////////////////// 

[
        local,
        object,
        uuid(e707dcde-d1cd-11d2-bab9-00c04f8eceae),
        pointer_default(unique)
]
interface IAssemblyCache : IUnknown
{
    cpp_quote("// {8cedc215-ac4b-488b-93c0-a50a49cb2fb8}")
    cpp_quote("DEFINE_GUID(FUSION_REFCOUNT_UNINSTALL_SUBKEY_GUID, 0x8cedc215, 0xac4b, 0x488b, 0x93, 0xc0, _
0xa5, 0x0a, 0x49, 0xcb, 0x2f, 0xb8);")
    cpp_quote("")
    cpp_quote("// {b02f9d65-fb77-4f7a-afa5-b391309f11c9}")
    cpp_quote("DEFINE_GUID(FUSION_REFCOUNT_FILEPATH_GUID, 0xb02f9d65, 0xfb77, 0x4f7a, 0xaf, 0xa5, 0xb3, 0x91, _
0x30, 0x9f, 0x11, 0xc9);")
    cpp_quote("")
    cpp_quote("// {2ec93463-b0c3-45e1-8364-327e96aea856}")
    cpp_quote("DEFINE_GUID(FUSION_REFCOUNT_OPAQUE_STRING_GUID, 0x2ec93463, 0xb0c3, 0x45e1, 0x83, 0x64, 0x32, _
0x7e, 0x96, 0xae, 0xa8, 0x56);")

    cpp_quote(" // {25df0fc1-7f97-4070-add7-4b13bbfd7cb8} // this GUID cannot be used for installing into GAC.")
    cpp_quote("DEFINE_GUID(FUSION_REFCOUNT_MSI_GUID,  0x25df0fc1, 0x7f97, 0x4070, 0xad, 0xd7, 0x4b, 0x13, 0xbb, 0xfd, _
0x7c, 0xb8); ")


    typedef struct _FUSION_INSTALL_REFERENCE_
    {
        DWORD  cbSize;
        DWORD  dwFlags;
        GUID   guidScheme; // contains one of the pre-defined guids.
        LPCWSTR szIdentifier;  // unique identifier for app installing this  assembly.
        LPCWSTR szNonCannonicalData;  // data is description; relevent to the guid above 
    } FUSION_INSTALL_REFERENCE, *LPFUSION_INSTALL_REFERENCE;

    typedef const FUSION_INSTALL_REFERENCE  *LPCFUSION_INSTALL_REFERENCE;


    typedef struct _ASSEMBLY_INFO
    {
        ULONG cbAssemblyInfo; // size of this structure for future expansion
        DWORD dwAssemblyFlags;
        ULARGE_INTEGER uliAssemblySizeInKB;
        LPWSTR pszCurrentAssemblyPathBuf;
        ULONG   cchBuf; // size of path buf.
    } ASSEMBLY_INFO;

    cpp_quote("#define IASSEMBLYCACHE_INSTALL_FLAG_REFRESH       (0x00000001)")
    cpp_quote("#define IASSEMBLYCACHE_INSTALL_FLAG_FORCE_REFRESH (0x00000002)")

    cpp_quote("#define IASSEMBLYCACHE_UNINSTALL_DISPOSITION_UNINSTALLED (1)")
    cpp_quote("#define IASSEMBLYCACHE_UNINSTALL_DISPOSITION_STILL_IN_USE (2)")
    cpp_quote("#define IASSEMBLYCACHE_UNINSTALL_DISPOSITION_ALREADY_UNINSTALLED (3)")
    cpp_quote("#define IASSEMBLYCACHE_UNINSTALL_DISPOSITION_DELETE_PENDING (4)")
    cpp_quote("#define IASSEMBLYCACHE_UNINSTALL_DISPOSITION_HAS_INSTALL_REFERENCES (5)")
    cpp_quote("#define IASSEMBLYCACHE_UNINSTALL_DISPOSITION_REFERENCE_NOT_FOUND (6)")

    cpp_quote("#define QUERYASMINFO_FLAG_VALIDATE        (0x00000001)")
    cpp_quote("#define QUERYASMINFO_FLAG_GETSIZE         (0x00000002)")

    // these flags are for dwAssemblyFlags field in struct _ASSEMBLY_INFO  
    cpp_quote("#define ASSEMBLYINFO_FLAG_INSTALLED       (0x00000001)")
    cpp_quote("#define ASSEMBLYINFO_FLAG_PAYLOADRESIDENT (0x00000002)")

    HRESULT UninstallAssembly(
        [in] DWORD dwFlags,
        [in] LPCWSTR pszAssemblyName, 
        [in] LPCFUSION_INSTALL_REFERENCE pRefData, 
        [out, optional] ULONG *pulDisposition
        );
 
    HRESULT QueryAssemblyInfo(
        [in] DWORD dwFlags,
        [in] LPCWSTR pszAssemblyName,
        [in, out] ASSEMBLY_INFO *pAsmInfo
        );
 
    HRESULT CreateAssemblyCacheItem( 
        [in] DWORD dwFlags,
        [in] PVOID pvReserved,
        [out] IAssemblyCacheItem **ppAsmItem,
        [in, optional] LPCWSTR pszAssemblyName  // uncanonicalized, comma separated name=value pairs.
        );
        
    HRESULT CreateAssemblyScavenger
    (
        [out]   IUnknown **ppUnkReserved
    );

    HRESULT InstallAssembly( // if you use this, fusion will do the streaming & commit.
        [in] DWORD dwFlags,
        [in] LPCWSTR pszManifestFilePath, 
        [in] LPCFUSION_INSTALL_REFERENCE pRefData
        );

}


/////////////////////////////////////////////////////////////////////////////// 
// 
// IAssemblyCacheItem
// 
/////////////////////////////////////////////////////////////////////////////// 

[
        local,
        object,
        uuid(9e3aaeb4-d1cd-11d2-bab9-00c04f8eceae),
        pointer_default(unique)
]
interface IAssemblyCacheItem : IUnknown
{
    cpp_quote("#define STREAM_FORMAT_COMPLIB_MODULE    0")
    cpp_quote("#define STREAM_FORMAT_COMPLIB_MANIFEST  1")
    cpp_quote("#define STREAM_FORMAT_WIN32_MODULE      2")
    cpp_quote("#define STREAM_FORMAT_WIN32_MANIFEST    4")
    
    cpp_quote("#define IASSEMBLYCACHEITEM_COMMIT_FLAG_REFRESH       (0x00000001)")
    cpp_quote("#define IASSEMBLYCACHEITEM_COMMIT_FLAG_FORCE_REFRESH (0x00000002)")
    
    cpp_quote("#define IASSEMBLYCACHEITEM_COMMIT_DISPOSITION_INSTALLED (1)") // first time install
    cpp_quote("#define IASSEMBLYCACHEITEM_COMMIT_DISPOSITION_REFRESHED (2)") // overwrite, if existing
    cpp_quote("#define IASSEMBLYCACHEITEM_COMMIT_DISPOSITION_ALREADY_INSTALLED (3)") // existing, 
    

    HRESULT CreateStream(
        [in] DWORD dwFlags,                         // For general API flags
        [in] LPCWSTR pszStreamName,                 // Name of the stream to be passed in
        [in] DWORD dwFormat,                        // format of the file to be streamed in.
        [in] DWORD dwFormatFlags,                   // format-specific flags
        [out] IStream **ppIStream,
        [in, optional] ULARGE_INTEGER *puliMaxSize  // Max size of the Stream.
        );
 
    HRESULT Commit
    (
        [in] DWORD dwFlags, // For general API flags like IASSEMBLYCACHEITEM _COMMIT_FLAG_REFRESH 
        [out, optional] ULONG *pulDisposition
    ); 
 
    HRESULT AbortItem(); // If you have created IAssemblyCacheItem and don't plan to use it, its good idea to call 
    AbortItem before releasing it.

}



/////////////////////////////////////////////////////////////////////////////// 
// 
// IAssemblyName
// 
/////////////////////////////////////////////////////////////////////////////// 

[
        local,
        object,
        uuid(CD193BC0-B4BC-11d2-9833-00C04FC31D2E),
        pointer_default(unique)
]
interface IAssemblyName: IUnknown
{
    typedef [unique] IAssemblyName *LPASSEMBLYNAME;
    
    typedef enum {
         CANOF_PARSE_DISPLAY_NAME = 0x1,
         CANOF_SET_DEFAULT_VALUES = 0x2
    } CREATE_ASM_NAME_OBJ_FLAGS;
    
    typedef enum
    {
        ASM_NAME_PUBLIC_KEY = 0,
        ASM_NAME_PUBLIC_KEY_TOKEN,
        ASM_NAME_HASH_VALUE,
        ASM_NAME_NAME,
        ASM_NAME_MAJOR_VERSION,
        ASM_NAME_MINOR_VERSION,
        ASM_NAME_BUILD_NUMBER,
        ASM_NAME_REVISION_NUMBER,
        ASM_NAME_CULTURE,
        ASM_NAME_PROCESSOR_ID_ARRAY,
        ASM_NAME_OSINFO_ARRAY,
        ASM_NAME_HASH_ALGID,
        ASM_NAME_ALIAS,
        ASM_NAME_CODEBASE_URL,
        ASM_NAME_CODEBASE_LASTMOD,
        ASM_NAME_NULL_PUBLIC_KEY,
        ASM_NAME_NULL_PUBLIC_KEY_TOKEN,
        ASM_NAME_CUSTOM,
        ASM_NAME_NULL_CUSTOM,                
        ASM_NAME_MVID,
        ASM_NAME_MAX_PARAMS
    } ASM_NAME;
    
    typedef enum
    {
        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_DISPLAY_FLAGS;
    
    typedef enum
    {
        ASM_CMPF_NAME            = 0x1,
        ASM_CMPF_MAJOR_VERSION   = 0x2,
        ASM_CMPF_MINOR_VERSION   = 0x4,
        ASM_CMPF_BUILD_NUMBER    = 0x8,
        ASM_CMPF_REVISION_NUMBER = 0x10,
        ASM_CMPF_PUBLIC_KEY_TOKEN = 0x20,
        ASM_CMPF_CULTURE         = 0x40,
        ASM_CMPF_CUSTOM          = 0x80,
        ASM_CMPF_ALL = ASM_CMPF_NAME | ASM_CMPF_MAJOR_VERSION | ASM_CMPF_MINOR_VERSION |
                       ASM_CMPF_REVISION_NUMBER | ASM_CMPF_BUILD_NUMBER |
                       ASM_CMPF_PUBLIC_KEY_TOKEN | ASM_CMPF_CULTURE | ASM_CMPF_CUSTOM,
        // For strongly named assemblies, ASM_CMPF_DEFAULT==ASM_CMPF_ALL.
        // For simply named assemblies, this is also true, however, when
        // performing IAssemblyName::IsEqual, the build number/revision 
        // number will be removed from the comparision.
        ASM_CMPF_DEFAULT = 0x100
    } ASM_CMP_FLAGS;                       

    HRESULT SetProperty(
        [in]    DWORD  PropertyId, 
        [in]    LPVOID pvProperty,
        [in]    DWORD  cbProperty);

    HRESULT GetProperty(
        [in]         DWORD    PropertyId, 
        [out]        LPVOID   pvProperty,
        [in, out]    LPDWORD  pcbProperty);

    HRESULT Finalize();

    HRESULT  GetDisplayName(
        [out]       LPOLESTR  szDisplayName,
        [in, out]   LPDWORD   pccDisplayName,
        [in]        DWORD     dwDisplayFlags);

    HRESULT BindToObject(
        [in]      REFIID               refIID,
        [in]      IUnknown            *pUnkSink, 
        [in]      IUnknown            *pUnkContext,
        [in]      LPCOLESTR            szCodeBase,
        [in]      LONGLONG             llFlags,
        [in]      LPVOID               pvReserved,
        [in]      DWORD                cbReserved,
        [out]     LPVOID               *ppv);


    HRESULT GetName(
        [in, out] LPDWORD lpcwBuffer,
        [out] WCHAR *pwzName);
        
    HRESULT GetVersion(
        [out] LPDWORD pdwVersionHi,
        [out] LPDWORD pdwVersionLow);

    HRESULT IsEqual(
        [in] IAssemblyName *pName,
        [in] DWORD dwCmpFlags);
        
    HRESULT Clone(
        [out] IAssemblyName **pName);
        

}

/////////////////////////////////////////////////////////////////////////////// 
// 
// IAssemblyEnum
// 
/////////////////////////////////////////////////////////////////////////////// 
[
        local,
        object,
        uuid(21b8916c-f28e-11d2-a473-00c04f8ef448),
        pointer_default(unique)
]
interface IAssemblyEnum : IUnknown
{

    HRESULT GetNextAssembly
    (
        [in]                  LPVOID                pvReserved,
        [out]                 IAssemblyName       **ppName,
        [in]                  DWORD                 dwFlags
    );

    HRESULT Reset(void);

    HRESULT Clone 
    (
        [out] IAssemblyEnum **ppEnum
    );
    
}


/////////////////////////////////////////////////////////////////////////////// 
// 
// IInstallReferenceItem
// 
/////////////////////////////////////////////////////////////////////////////// 

[
        local,
        object,
        uuid(582dac66-e678-449f-aba6-6faaec8a9394),
        pointer_default(unique)
]
interface IInstallReferenceItem : IUnknown
{
    HRESULT GetReference
    (
    [out] LPFUSION_INSTALL_REFERENCE *ppRefData,
    [in]  DWORD dwFlags,
    [in]  LPVOID pvReserved
    );
}

/////////////////////////////////////////////////////////////////////////////// 
// 
// IInstallReferenceEnum
// 
/////////////////////////////////////////////////////////////////////////////// 

[
        local,
        object,
        uuid(56b1a988-7c0c-4aa2-8639-c3eb5a90226f),
        pointer_default(unique)
]
interface IInstallReferenceEnum : IUnknown
{
    HRESULT GetNextInstallReferenceItem
            (
            [out] IInstallReferenceItem **ppRefItem,
            [in]  DWORD dwFlags,
            [in]  LPVOID pvReserved
            );
}

#pragma midl_echo("STDAPI CreateInstallReferenceEnum(IInstallReferenceEnum **ppRefEnum, IAssemblyName *pName, DWORD dwFlags, _
LPVOID pvReserved);      ")
#pragma midl_echo("STDAPI CreateAssemblyEnum(IAssemblyEnum **pEnum, IUnknown *pUnkReserved, IAssemblyName *pName, DWORD dwFlags, _
LPVOID pvReserved);      ") 
#pragma midl_echo("STDAPI CreateAssemblyNameObject(LPASSEMBLYNAME *ppAssemblyNameObj, LPCWSTR szAssemblyName, DWORD dwFlags, _
LPVOID pvReserved);             ")
#pragma midl_echo("STDAPI CreateAssemblyCache(IAssemblyCache **ppAsmCache, DWORD dwReserved); ")
#pragma midl_echo("STDAPI GetCachePath(ASM_CACHE_FLAGS dwCacheFlags, LPWSTR pwzCachePath, PDWORD pcchPath); ")

DOC: Global Assembly Cache (GAC) APIs Are Not Documented in the .NET Framework Software Development Kit (SDK) Documentation (317540)

SUMMARY

MORE INFORMATION

IAssemblyCache Interface

FUSION_INSTALL_REFERENCE Structure

ASSEMBLY_INFO Structure

IAssemblyCache::UninstallAssembly Method

IAssemblyCache::QueryAssemblyInfo Method

IAssemblyCache::InstallAssembly Method

IAssemblyName Interface

CREATE_ASM_NAME_OBJ_FLAGS Enumeration

ASM_NAME Enumeration

IAssemblyName::SetProperty Method

IAssemblyName::GetProperty Method

IAssemblyName::Finalize Method

IAssemblyName::GetDisplayName Method

IAssemblyName::GetName Method

IAssemblyName::GetVersion Method

IAssemblyName::IsEqual Method

IAssemblyName::Clone Method

IAssemblyEnum Interface

ASM_CACHE_FLAGS Enumeration

IAssemblyEnum::GetNextAssembly Method

IInstallReferenceItem Interface

IInstallReferenceItem::GetReference Method

IInstallReferenceEnum Interface

IInstallReferenceEnum::GetNextInstallReferenceItem Method

GetCachePath API