Assembly Manifests

Artikkeli
03/10/2023

An assembly manifest is an XML file that describes a side-by-side assembly. Assembly manifests describe the names and versions of side-by-side assemblies, files, and resources of the assembly, as well as the dependence of the assembly on other side-by-side assemblies. Correct installation, activation, and execution of side-by-side assemblies requires that the assembly manifest always accompany an assembly on the system.

For a complete listing of the XML schema, see Manifest File Schema.

Assembly manifests have the following elements and attributes.

Element	Attributes	Required
assembly		Yes
	manifestVersion	Yes
noInheritable		No
assemblyIdentity		Yes
	type	Yes
	name	Yes
	language	No
	processorArchitecture	No
	version	Yes
	publicKeyToken	No
dependency		No
dependentAssembly		No
file		No
	name	Yes
	hashalg	No
	hash	No
comClass		No
	description	No
	clsid	Yes
	threadingModel	No
	tlbid	No
	progid	No
	miscStatus	No
	miscStatusIcon	No
	miscStatusContent	No
	miscStatusDocPrint	No
	miscStatusThumbnail	No
typelib		No
	tlbid	Yes
	version	Yes
	helpdir	Yes
	resourceid	No
	flags	No
comInterfaceExternalProxyStub		No
	iid	Yes
	baseInterface	No
	numMethods	No
	name	No
	tlbid	No
	proxyStubClsid32	No
comInterfaceProxyStub		No
	iid	Yes
	name	Yes
	tlbid	No
	baseInterface	No
	numMethods	No
	proxyStubClsid32	No
	threadingModel	No
windowClass		No
	versioned	No

File Location

Assembly manifests can be installed in three locations:

As manifests that accompany shared assemblies, assembly manifests should be installed as a separate file in the side-by-side assembly cache. This is usually the WinSxS folder in the Windows directory.
As manifests that accompany private assemblies, assembly manifests should installed in the directory structure of the application. This is usually a separate file in the same folder as the application's executable file.
As a resource in a DLL, the assembly is available for the private use of the DLL. An assembly manifest cannot be included as a resource in an EXE. An EXE file may include an application manifest as a resource.

File Name Syntax

The name of an assembly manifest is any valid file name followed by .manifest.

For example, an assembly manifest that refers to myassembly would use the following file name syntax: myassembly.<resource ID>.manifest. You can omit the <resource ID> field if the assembly manifest is being installed as a separate file or if the resource ID is 1.

Note

Because of the way side-by-side searches for private assemblies, the following naming restrictions apply when packaging a DLL as a private assembly. A recommended way of doing this is to put the assembly manifest in the DLL as a resource. In this case, the resource ID must equal 1 and the name of the private assembly may be the same as the name of the DLL. For example, if the name of the DLL is Microsoft.Windows.mysample.dll, the value of the name attribute used in the assemblyIdentity element of the manifest may also be Microsoft.Windows.mysample. An alternate way is to put the assembly manifest in a separate file. In this case, the name of the assembly and its manifest must be different than the name of the DLL. For example, Microsoft.Windows.mysampleAsm, Microsoft.Windows.mysampleAsm.manifest, and Microsoft.Windows.Mysample.dll. For more information about how side-by-side searches for private assemblies, see Assembly Searching Sequence.

Elements

Names of elements and attributes are case-sensitive. The values of elements and attributes are case-insensitive, except for the value of the type attribute.

assembly

A container element. Its first subelement must be an assemblyIdentity or noInheritable element. The assembly manifest uniquely describes the side-by-side assembly identified by the assemblyIdentity. Required.

The assembly element must be in the namespace "urn:schemas-microsoft-com:asm.v1". Child elements of the assembly must also be in this namespace, by inheritance or by tagging.

The assembly element has the following attribute.

Attribute	Description
manifestVersion	The manifestVersion attribute must be set to 1.0.

noInheritable

Include this element in an assembly manifest to indicate that the assembly manages the activation contexts and its objects. The noInheritable element must be a subelement of an assembly element. The assemblyIdentity element should come after any noInheritable element. The noInheritable element is required in the assembly manifest if the assembly is used by any application manifests that include the noInherit element. A noInheritable element in an application manifest has no effect. A noInheritable element has no child elements.

assemblyIdentity

Describes and uniquely identifies a side-by-side assembly.

As the first subelement of an assembly element, assemblyIdentity describes and uniquely identifies the side-by-side assembly that owns this assembly manifest. This is called the DEF-context assemblyIdentity of the assembly manifest.

As the first subelement of a dependentAssembly element, assemblyIdentity describes and uniquely identifies a side-by-side assembly that is used by the DEF-context assemblyIdentity. This is called a REF-context assemblyIdentity of the assembly manifest. The DEF-context assembly requires the REF-context assembly to work correctly. Note that every REF-context assemblyIdentity must exactly match a corresponding DEF-context assemblyIdentity in the referenced assembly's own assembly manifest.

This element has no subelements. The assemblyIdentity element does have the following attributes.

Attribute	Description
type	Specifies the assembly type. The value must be win32 and in lower case. Required.
name	Uniquely names the assembly. Use the following format for the assembly name: Organization.Division.Name. For example, Microsoft.Windows.mysampleAsm. Required. Note that in the case of a DLL packaged as a private assembly with a separate manifest file, the name of the assembly must be different than the name of the DLL and the manifest.
language	Identifies the language of the assembly. Optional. If the assembly is language-specific, specify the DHTML language code. In the DEF-context assemblyIdentity of an assembly manifest intended for worldwide use (language neutral) omit the language attribute. In a REF-context assemblyIdentity of an assembly manifest intended for worldwide use (language neutral) set the value of language to "*".
processorArchitecture	Specifies the processor. The valid values are x86 for 32-bit Windows and ia64 for 64-bit Windows. Optional.
version	Specifies the assembly version. Use the four-part version format: mmmmm.nnnnn.ooooo.ppppp. Each of the parts separated by periods can be 0-65535 inclusive. For more information, see Assembly Versions. Required.
publicKeyToken	A 16-character hexadecimal string representing the last 8 bytes of the SHA-1 hash of the public key under which the assembly is signed. The public key used to sign the catalog must be 2048 bits or greater. Required for shared side-by-side assemblies.

dependency

A container element including at least one dependentAssembly. The first subelement must be a dependentAssembly element. A dependency has no attributes. Optional.

dependentAssembly

The first subelement must be an assemblyIdentity element that describes and uniquely identifies a side-by-side assembly that is used by the side-by-side assembly that owns this assembly manifest. Every dependentAssembly must be inside exactly one dependency. Optional.

file

Contains files used by a side-by-side assembly. Contains comClass, typelib, windowClass, comInterfaceProxyStub subelements. Optional.

The file element has the following attributes.

Attribute	Description
name	Name of the file, for example, Conctl32.dll.
hashalg	Algorithm used to create a hash of the file. This value should be SHA1.
hash	A hash of the file referred to by name. A hexadecimal string of length depending on the hash algorithm.

comClass

A subelement of a file element. Optional.

The comClass element has the following attributes.

Attribute	Description
description	Class name.
clsid	The GUID that uniquely identifies the Class. Required. The value must be in the format of a valid GUID.
threadingModel	The threading model used by in-process COM classes. If this property is null, then no threading model is used. The component is created on the main thread of the client and calls from other threads are marshaled to this thread. Optional. Valid values are: "Apartment", "Free", "Both", and "Neutral".
tlbid	GUID for the type library for this COM component. The value must be in the format of a GUID. Optional.
progid	Version-dependent programmatic identifier associated with the COM component. The format of a ProgID is <vendor>.<component>.<version>.
miscStatus	Duplicates in the assembly manifest the information provided by the MiscStatus registry key. If values for the miscStatusIcon, miscStatusContent, miscStatusDocprint, or miscStatusThumbnail attributes are not found, the corresponding default value listed in miscStatus is used for the missing attributes. The value can be a comma-delimited list of the attribute values from the table below. You can use this attribute if the COM class is an OCX class that requires Miscstatus registry key values.
miscStatusIcon	Duplicates in the assembly manifest the information provided by DVASPECT_ICON. It can provide an icon of an object. The value can be a comma-delimited list of the attribute values from the table below. You can use this attribute if the COM class is an OCX class that requires Miscstatus registry key values.
miscStatusContent	Duplicates in the assembly manifest the information provided by DVASPECT_CONTENT. It can provide a compound document displayable for a screen or printer. The value can be a comma-delimited list of the attribute values from the table below. You can use this attribute if the COM class is an OCX class that requires Miscstatus registry key values.
miscStatusDocprint	Duplicates in the assembly manifest the information provided by DVASPECT_DOCPRINT. It can provide an object representation displayable on the screen as though printed to a printer. The value can be a comma-delimited list of the attribute values from the table below. You can use this attribute if the COM class is an OCX class that requires Miscstatus registry key values.
miscStatusThumbnail	Duplicates in an assembly manifest the information provided by DVASPECT_THUMBNAIL. It can provide a thumbnail of an object displayable in a browsing tool. The value can be a comma-delimited list of the attribute values from the table below. You can use this attribute if the COM class is an OCX class that requires Miscstatus registry key values.

The comClass element can have <progid>... elements as children, which list the version dependent progids.

The following example shows a comClass element included in a file element.

<file name="sampleu.dll">
        <comClass description="Font Property Page"
    clsid="{0BE35200-8F91-11CE-9DE3-00AA004BB851}"
          threadingModel = "Both"
             tlbid = "{44EC0535-400F-11D0-9DCD-00A0C90391D3}"/>
        <comClass description="Color Property Page"
    clsid="{0BE35201-8F91-11CE-9DE3-00AA004BB851}" 
    progid="ABC.Registrar"/>
    </file>

If your COM class is an OCX class that requires the MiscStatus registry subkey to specify how to create and display an object, you can enable the object by duplicating this information in the assembly manifest. Specify the object's characteristics by using the miscStatus, miscStatusIcon, miscStatusContent, miscStatusDocprint, and miscStatusThumbnail attributes of the comClass element. Set these attributes to a comma-separated list of attribute values from the following table. These attributes duplicate the information that would be provided by a DVASPECT enumeration. If a no value is found for miscStatusIcon, miscStatusContent, miscStatusDocprint, or miscStatusThumbnail, the default values specified in miscStatus is used. Use attribute values from the following table. These correspond to the bit flags of a OLEMISC enumeration.

Attribute Value	OLEMISC Constant
recomposeonresize	OLEMISC_RECOMPOSEONRESIZE
onlyiconic	OLEMISC_ONLYICONIC
insertnotreplace	OLEMISC_INSERTNOTREPLACE
static	OLEMISC_STATIC
cantlinkinside	OLEMISC_CANTLINKINSIDE
canlinkbyole1	OLEMISC_CANLINKBYOLE1
islinkobject	OLEMISC_ISLINKOBJECT
insideout	OLEMISC_INSIDEOUT
activatewhenvisible	OLEMISC_ACTIVATEWHENVISIBLE
renderingisdeviceindependent	OLEMISC_RENDERINGISDEVICEINDEPENDENT
invisibleatruntime	OLEMISC_INVISIBLEATRUNTIME
alwaysrun	OLEMISC_ALWAYSRUN
actslikebutton	OLEMISC_ACTSLIKEBUTTON
actslikelabel	OLEMISC_ACTSLIKELABEL
nouiactivate	OLEMISC_NOUIACTIVATE
alignable	OLEMISC_ALIGNABLE
simpleframe	OLEMISC_SIMPLEFRAME
setclientsitefirst	OLEMISC_SETCLIENTSITEFIRST
imemode	TOLEMISC_IMEMODE
ignoreativatewhenvisible	OLEMISC_IGNOREACTIVATEWHENVISIBLE
wantstomenumerge	OLEMISC_WANTSTOMENUMERGE
supportsmultilevelundo	OLEMISC_SUPPORTSMULTILEVELUNDO

typelib

A subelement of a file element. Optional.

The typelib element has the attributes shown in the following table.

Attribute	Description
tlbid	The unique ID of the type library. Required.
version	The two-part version number of the type library. If only the minor version number increases, all the features of the previous type library are supported in a compatible way. If the major version number changes, code that compiled against the type library must be recompiled. The version number of the type library may differ from the version number of the application. Required.
helpdir	The directory where the Help file for the types in the type library is located. If the application supports type libraries for multiple languages, the libraries may refer to different file names in the Help file directory. If no value, then specify "". Required.
resourceid	The hexadecimal string representation of the locale identifier (LCID). It is one to four hexadecimal digits with no 0x prefix and no leading zeros. The LCID may have a neutral sublanguage identifier. For more information, see Locale Identifiers. Optional.
flags	The string representation of the type library flags for this type library. Specifically, it should be one of "RESTRICTED", "CONTROL", "HIDDEN" and "HASDISKIMAGE". These are the values of the LIBFLAGS enumeration, and are the same flags specified in the uLibFlags parameter of the ICreateTypeLib::SetLibFlags method. Optional.

The following example shows a typelib element included in a file element.

<file name="sampleu.dll">
       <typelib tlbid="{44EC0535-400F-11D0-9DCD-00A0C90391D3}"
       version="1.0" helpdir=""/>
</file>

comInterfaceExternalProxyStub

The comInterfaceExternalProxyStub is a subelement of an assembly element and is used for automation interfaces. For example, IDispatch and its derived interfaces. Optional.

The default proxy-stub implementation is adequate for most automation interfaces, such as interfaces derived from IDispatch. The interface proxy stub, and all other external proxy-stub interface implementations, must be listed in the comInterfaceExternalProxyStub. The comInterfaceExternalProxyStub element has the attributes shown in the following table.

Attribute	Description
iid	The IID of the interface for which the proxy is being declared. Required. The value should be in the form: "{iid}".
baseInterface	The IID of the interface from which the one described by the iid attribute is derived. This attribute is optional. The value should be in the form: "{iid}".
numMethods	The number of methods implemented by the interface. This attribute is optional. The value should be in the form: "n".
name	Name of the interface as it would appear in code. For example, "IViewObject". This should not be a descriptive string. This attribute is optional. The value should be in the form: "name".
tlbid	The type library that contains the description of the interface specified by the iid attribute. This attribute is optional. The value should be in the form: "{tlbid}" .
proxyStubClsid32	Maps an IID to a CLSID in 32-bit proxy DLLs.

The following example shows a comInterfaceExternalProxyStub element.

<comInterfaceExternalProxyStub 
  name="IAxWinAmbientDispatch" 
    iid="{B6EA2051-048A-11D1-82B9-00C04FB9942E}" 
    numMethods="35" 
  baseInterface="{00000000-0000-0000-C000-000000000046}"/>

comInterfaceProxyStub

A subelement of a file element. Optional.

If a file in the assembly implements a proxy stub, the corresponding file tag must include a comInterfaceProxyStub subelement having attributes that are identical to a comInterfaceProxyStub element. Marshaling interfaces between processes and threads may not work as expected if you omit some of the comInterfaceProxyStub dependencies for your component.

The comInterfaceProxyStub element has the following attributes.

Attribute	Description
iid	The .IID of the interface for which the proxy is being declared. Required. The value should be in the form: "{iid}".
name	Name of the interface as it would appear in code. For example, "IViewObject". This should not be a descriptive string. This attribute is optional. The value should be in the form: "name".
tlbid	The type library that contains the description of the interface specified by the iid attribute. This attribute is optional. The value should be in the form: "{tlbid}".
baseInterface	The IID of the interface from which the one described by the iid attribute is derived. This attribute is optional. The value should be in the form: "{iid}".
numMethods	The number of methods implemented by the interface. This attribute is optional. The value should be in the form: "n".
proxyStubClsid32	Maps an IID to a CLSID in 32-bit proxy DLLs.
threadingModel	The threading model used by in-process COM classes. If this property is null, then no threading model is used. The component is created on the main thread of the client and calls from other threads are marshaled to this thread. Optional. Valid values are: "Apartment", "Free", "Both", and "Neutral".

windowclass

The name of a windows class that is to be versioned. The windowclass element has the following attribute.

Attribute	Description
versioned	This attribute controls whether or not the internal window class name used in registration contains the version of the assembly containing the window class. The value of this attribute can be "yes" or "no". The default is "yes". The value "no" should only be used if the same window class is defined by a side-by-side component and an equivalent non-side-by-side component and you wish to treat them as the same window class. Note that the usual rules about window class registration apply only the first component that registers the window class will be able to register it since it is not versioned.

Attribute

Description

versioned

This attribute controls whether or not the internal window class name used in registration contains the version of the assembly containing the window class. The value of this attribute can be "yes" or "no". The default is "yes". The value "no" should only be used if the same window class is defined by a side-by-side component and an equivalent non-side-by-side component and you wish to treat them as the same window class. Note that the usual rules about window class registration apply only the first component that registers the window class will be able to register it since it is not versioned.

The following example shows a windowclass element included in a file element.

<file name="comctl32.dll">
        <windowClass versioned="no">ToolbarWindow32</windowClass>
</file>

Example

The following is an example of an assembly manifest.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" 
manifestVersion="1.0">
    <assemblyIdentity type="win32" name="Microsoft.Tools.SampleAssembly" version="6.0.0.0" processorArchitecture="x86" publicKeyToken="0000000000000000"/>
    <file name="sampleu.dll" hash="3eab067f82504bf271ed38112a4ccdf46094eb5a" hashalg="SHA1">
        <comClass description="Font Property Page" clsid="{0BE35200-8F91-11CE-9DE3-00AA004BB851}"/>
        <comClass description="Color Property Page" clsid="{0BE35201-8F91-11CE-9DE3-00AA004BB851}"/>
        <comClass description="Picture Property Page" clsid="{0BE35202-8F91-11CE-9DE3-00AA004BB851}"/>
    </file>
    <file name="bar.dll" hash="ac72753e5bb20446d88a48c8f0aaae769a962338" hashalg="SHA1"/>
    <file name="foo.dll" hash="a7312a1f6cfb46433001e0540458de60adcd5ec5" hashalg="SHA1">
        <comClass description="Registrar Class" clsid="{44EC053A-400F-11D0-9DCD-00A0C90391D3}" progid="ATL.Registrar"/>
    <comInterfaceProxyStub iid="{B6EA2051-048A-11D1-82B9-00C04FB9942E}" name=" IAxWinAmbientDispatch " tlbid="{34EC053A-400F-11D0-9DCD-00A0C90391D3}"/>
        <typelib tlbid="{44EC0535-400F-11D0-9DCD-00A0C90391D3}" version="1.0" helpdir=""/>
    </file>
    <file name="sampledll.dll" hash="ba62960ceb15073d2598379307aad84f3a73dfcb" hashalg="SHA1"/>
<windowClass>ToolbarWindow32</windowClass>
        <windowClass>ComboBoxEx32</windowClass>
        <windowClass>sample_trackbar32</windowClass>
        <windowClass>sample_updown32</windowClass>
</assembly>

Jaa

Assembly Manifests

File Location

File Name Syntax

Elements

Example

Palaute

Lisäresursseja