Proxies for Managed Assemblies

ProxyGen.exe generates proxy types that are based on public types in the object model of the host application. For the most part, the proxy types have the same members as the host types, and maintain a similar type hierarchy. However, there are some characteristics of managed host types that ProxyGen.exe does not support, and the proxy types have some differences from the host types.

For information about the structure of the proxy code file, see Architecture of Generated Proxy Code.

This topic provides the following information:

• Unsupported features of managed object models

• Conversion of host types to proxy types

• Conversion of host members to proxy members

Unsupported Features of Managed Object Models

There are some features of types and members in managed object models that ProxyGen.exe does not support. When the assembly that you pass to ProxyGen.exe contains code that uses one of these features, ProxyGen.exe omits the type or member from the proxy descriptor file.

ProxyGen.exe does not support the following features:

• Types or members that are declared as private, internal, or external.

• Generic types or methods.

• Nested types.

Conversion of Host Types to Proxy Types

During conversion, ProxyGen.exe applies the HostTypeAttribute attribute to all proxy types, with the exception of entry points. For more information, see Architecture of Generated Proxy Code.

The proxy types that are generated by ProxyGen.exe have the following differences from the host types.

Classes

ProxyGen.exe generates a proxy class for every public class in the host object model. The proxy class is converted exactly as it is declared in the host object model, with the following exceptions:

• ProxyGen.exe derives the proxy class from MarshalByRefObject. This enables instances of the proxy class to be marshaled between the add-in and the host application.

  However, if the host class derives from a class in a different assembly and the base class does not have MarshalByRefObject in its inheritance hierarchy, then ProxyGen.exe does not derive the proxy class from MarshalByRefObject. ProxyGen.exe displays an error to warn you that the proxy class is not a usable proxy. In this case, you must redesign the host application's object model so that the host class or the base class has MarshalByRefObject in its inheritance hierarchy.

• ProxyGen.exe applies the abstract keyword to the proxy class.

• Any defined constructors in the host class are not generated in the proxy class. The proxy class has a default constructor that is used internally by Visual Studio Tools for Applications, and is not intended to be used in the add-in code.

  Therefore, add-in developers cannot use the new keyword to create an instance of the object. The following declarations are not supported for proxy classes.

  Dim robot1 as New Robot()
  

  Robot robot1 = new Robot();
  

  The following declarations are supported for proxy classes (if the host object model provides a factory method called CreateRobot).

  Dim robot1 as Robot = Application.CreateRobot()
  

  Robot robot1 = Application.CreateRobot();
  

Interfaces

ProxyGen.exe generates a proxy interface for every public interface in the object model. The proxy interface has the same definition as the host interface.

Structs

ProxyGen.exe generates a proxy class for every public struct in the host object model. The proxy classes are abstract, and derive from MarshalByRefObject. Add-in developers can use the proxy class in the same way that they use the host struct. Instances of the proxy class are marshaled between the add-in and the host application as the host struct type.

Where possible, it is recommended that you include only serializable structs in your object model, and that you create your own proxies for the structs, rather than using ProxyGen.exe. For more information, see Creating Proxies for Managed Structs.

Enumerations

ProxyGen.exe generates an enumeration for every public enumeration in the host object model. However, the generated enumeration is not a proxy; that is, it does not derive from MarshalByRefObject, and objects declared by the add-in that contain one of the enumeration values are not marshaled between the add-in and the host application.

Exceptions

ProxyGen.exe generates a partial definition of a proxy exception for every public custom exception that is defined in the host object model. For more information about proxy exceptions, see Architecture of Generated Proxy Code and Creating Proxies for Custom Exceptions.

Delegates

ProxyGen.exe generates a proxy delegate for every public delegate in the object model. The proxy delegate has the same definition as the host delegate.

Attributes

All attributes that are applied to types and members in the host object model are also generated in the proxy code. This includes any constructor parameters and named parameters that are defined in the attribute declaration.

Attributes that are applied to the following programming elements in the host object model are ignored:

• Assembly

• Module

Attributes that are applied to the following programming elements in the host object model are valid:

• Class

• Delegate

• Enum

• Event

• Field

• Interface

• Method

• Parameter

• ReturnValue

• Struct

  Note

  Certain field-level attributes might be invalid when the attributes are applied to properties, which might result in code that does not compile.

  Note

  If the DefaultParameterValueAttribute is applied to an array type that is defined in a Visual Basic object model, ProxyGen.exe does not generate this attribute.

Conversion of Host Members to Proxy Members

During conversion, ProxyGen.exe applies some general changes to static and non-static members. For more information, see Architecture of Generated Proxy Code.

In addition, the members of proxy types have the following differences from the members of managed host types.

Methods and Properties

ProxyGen.exe generates code to match the original signatures of all public methods and properties.

Indexer Properties

ProxyGen.exe generates an indexer property in the proxy code only if the indexer property in the host object model is named Item. Otherwise, ProxyGen.exe ignores indexer properties in the host object model.

Parameterized Properties

If the host object model contains parameterized properties that are implemented using Visual Basic, ProxyGen.exe converts the parameterized properties into equivalent methods in C#.

The following code examples demonstrate this. The first example shows the parameterized property definition in Visual Basic. The second example shows the generated proxy methods.

Public Property Shapes (nameOfShape As String, typeOfShape _
    As ShapeType) As Shape
End Property

public Shape get_Shape(string nameOfShape, ShapeType typeOfShape)
{
}
public void set_Shape(string nameOfShape, ShapeType typeofShape,
    Shape value)
{
}

Fields

ProxyGen.exe supports fields only in the following cases:

• The field is a member of a custom exception in the host object model. ProxyGen.exe recreates all fields in the proxy exception. For more information about proxy exceptions, see Architecture of Generated Proxy Code and Creating Proxies for Custom Exceptions.

• The field is a constant that is declared by using the const keyword. ProxyGen.exe preserves the syntax of the constant field in the proxy type. The values of constant fields are not marshaled between the add-in and the host application; each constant value exists separately in the add-in and the host application.

In all other cases, ProxyGen.exe ignores fields in the host object model. ProxyGen.exe will not recreate these fields in the proxy code.

See Also

Concepts

Architecture of Generated Proxy Code

Creating Proxies

Defining Entry Points and Other Proxy Changes

ProxyGen Descriptor Schema Reference

Reference

Proxies for COM Type Libraries

Proxy Generation Tool (ProxyGen.exe)