Type Equivalence and Embedded Interop Types

公告

Beginning with the .NET Framework version 4, the common language runtime supports embedding type information for COM types directly into managed assemblies, instead of requiring the managed assemblies to obtain type information for COM types from interop assemblies. Because the embedded type information includes only the types and members that are actually used by a managed assembly, two managed assemblies might have very different views of the same COM type. Each managed assembly has a different Type object to represent its view of the COM type. The common language runtime supports type equivalence between these different views for interfaces, structures, enumerations, and delegates.

Type equivalence means that a COM object that is passed from one managed assembly to another can be cast to the appropriate managed type in the receiving assembly.

Note
Type equivalence and embedded interop types simplify the deployment of applications and add-ins that use COM components, because it is not necessary to deploy interop assemblies with the applications. Developers of shared COM components still have to create primary interop assemblies (PIAs) if they want their components to be used by earlier versions of the .NET Framework.

Type equivalence

Equivalence of COM types is supported for interfaces, structures, enumerations, and delegates. COM types qualify as equivalent if all of the following are true:

The types are both interfaces, or both structures, or both enumerations, or both delegates.
The types have the same identity, as described in the next section.
Both types are eligible for type equivalence, as described in the Marking COM Types for Type Equivalence section.

Type Identity

Two types are determined to have the same identity when their scopes and identities match, in other words, if they each have the TypeIdentifierAttribute attribute, and the two attributes have matching Scope and Identifier properties. The comparison for Scope is case-insensitive.

If a type does not have the TypeIdentifierAttribute attribute, or if it has a TypeIdentifierAttribute attribute that does not specify scope and identifier, the type can still be considered for equivalence as follows:

For interfaces, the value of the GuidAttribute is used instead of the TypeIdentifierAttribute.Scope property, and the Type.FullName property (that is, the type name, including the namespace) is used instead of the TypeIdentifierAttribute.Identifier property.
For structures, enumerations, and delegates, the GuidAttribute of the containing assembly is used instead of the Scope property, and the Type.FullNameproperty is used instead of the Identifier property.

Marking COM Types for Type Equivalence

You can mark a type as eligible for type equivalence in two ways:

Apply the TypeIdentifierAttribute attribute to the type.
Make the type a COM import type. An interface is a COM import type if it has the ComImportAttribute attribute. An interface, structure, enumeration, or delegate is a COM import type if the assembly in which it is defined has the ImportedFromTypeLibAttribute attribute.

Using com type in managed code

COM types that are defined in an assembly are like any other managed types. Managed clients can create a new instance of a COM type in the usual way and obtain class information through metadata as they would for any other managed class. Method syntax can be inspected through an object viewer or obtained using reflection, just as it can with any other managed class. When the COM object returns a failure HRESULT, the .NET Framework client catches a corresponding exception.

There are two ways for your application to include the type information that enables interoperation with COM types:

Using embedded interop types: Beginning with the .NET Framework version 4, you can instruct the compiler to embed type information from an interop assembly into your executable. The compiler embeds only the type information that your application uses. You do not have to deploy the interop assembly with your application. This is the recommended technique.
Deploying interop assemblies: You can create a standard reference to an interop assembly. In this case, the interop assembly must be deployed with your application. If you employ this technique, and you are not using a private COM component, always reference the primary interop assembly (PIA) published by the author of the COM component you intend to incorporate in your managed code. For more information about producing and using primary interop assemblies, see Primary Interop Assemblies.

Note
When you use embedded interop types, you can embed them from the primary interop assembly published by the author of the COM component. However, you do not have to deploy the primary interop assembly with your application.

Using embedded interop types reduces the size of your application, because most applications do not use all the features of a COM component. The compiler is very efficient when it embeds type information; if your application uses only some of the methods on a COM interface, the compiler does not embed the unused methods. When an application that has embedded type information interacts with another such application, or interacts with an application that uses a primary interop assembly, the common language runtime uses type equivalence rules to determine whether two types with the same name represent the same COM type.

Obtaining and releasing a reference to a running COM object is just like obtaining and releasing a reference to any other running managed object. When .NET Framework clients obtain and release a reference to a COM object, the runtime maintains the reference count on the COM object just as any other COM client would, and .NET Framework clients can behave as if the object were subject to garbage collection, just as they would for any other managed server object.

Visual Studio makes it easy to embed type information into an application or add-in. For examples, see Walkthrough: Embedding Type Information from Microsoft Office Assemblies (C# and Visual Basic) and Walkthrough: Embedding Types from Managed Assemblies (C# and Visual Basic).

For code samples that accompany the topics of this section, see COM Interop Sample: .NET Client and COM Server.

The rules for type equivalence are discussed in Type Equivalence and Embedded Interop Types. However, you do not have to know these rules to use COM objects.