Creating Proxies for Managed Structs
You can expose public structs in a managed object model to add-ins by creating proxies for them. To ensure that the proxies for the structs work as expected, follow these guidelines:
Include only serializable structs in the object model (that is, structs that have the SerializableAttribute attribute).
Create your own proxies for the structs, rather than using ProxyGen.exe to automatically generate the proxies.
Creating Proxies for Serializable Structs
To expose serializable structs in the host application's object model to add-ins, you should define your own proxies for the structs. If you use ProxyGen.exe to generate proxies for the structs, it creates proxies that are defined as classes, rather than structs. Because the proxies used by the add-in are reference types, but the corresponding structs in the host application are value types, the proxies might behave unpredictably.
To define your own proxies for structs in the object model, perform the following steps as part of the overall process of integrating Visual Studio Tools for Applications with the host application:
After you use ProxyGen.exe to generate a proxy descriptor file for your object model, add the isExcluded attribute to each of the struct definitions to prevent ProxGen.exe from generating proxies for them in the proxy code file.
For more information about the isExcluded attribute, see Defining Entry Points and Other Proxy Changes.
After you use ProxyGen.exe to generate the proxy code file, define proxies for the structs in a separate code file that is compiled into the proxy assembly. The proxies must have the same definitions as the structs in the host application's object model, and they must also have the HostTypeAttribute attribute applied to them.
For step-by-step instructions for defining proxies for structs, see Walkthrough: Creating a Proxy Assembly. For more information about the HostTypeAttribute, see Architecture of Generated Proxy Code.
When you update the host application to load add-ins, add the structs to the type map in the host application. You must write your own code that does this. The type map provider that ProxyGen.exe generates will not add the structs to the type map, because you prevented ProxyGen.exe from generating proxies for the structs.
For step-by-step instructions for adding the structs to the type map, see Walkthrough: Modifying an Application to Load Add-Ins. For more information about the type map and type map provider, see Mapping Host Types to Proxy Types.
Creating Proxies for Non-Serializable Structs
If your object model contains non-serializable structs, it is strongly recommended that you make them serializable. If for some reason you cannot change the definitions of the structs to make them serializable, you can use ProxyGen.exe to generate proxies for the structs.
However, the generated proxies might not behave as expected in all cases. Because the proxies are defined as classes, rather than structs, this means that the proxies used by the add-in are reference types, and the corresponding structs in the host application are value types. This might cause unpredictable behavior.
To help ensure that the proxies work as expected, the structs in the host application must override the GetHashCode and Equals methods:
GetHashCode must return a hash code that is unique for each instance of the struct.
Equals must return true if the two struct references that are compared refer to the same object, and false if they refer to different objects. The easiest way to do this is to call ReferenceEquals in your implementation of Equals.
See Also
Tasks
Walkthrough: Creating a Proxy Assembly
Walkthrough: Modifying an Application to Load Add-Ins
Concepts
Defining Entry Points and Other Proxy Changes
Architecture of Generated Proxy Code