This download includes the executable program and source code for AutoProxyGen as well as a guide for use. To use VSTA with AutoProxyGen run the included setup file (SetupAutoProxyGen.js). A sample add-in which corrects the inheritence bug ProxyGen has with the ShapeAppBasicMFC sample is also included.
Related Links:
Blog- Tools to Automate VSTA 2.0 Integrations- AutoProxyGen & Templates
Video on MSN Videos- From ProxyGen to AutoProxyGen (text and code may be difficult to read due to compression)
Video for downloand- From ProxyGen to AutoProxyGen
Exert from AutoProxyGen Guide.doc:
The AutoProxyGen tool is designed to automate the process of using the ProxyGen tool included with the VSTA v 2.0 SDK. AutoProxyGen inputs file locations and uses these to create and run commands through ProxyGen to ultimately produce the proxy and HostTypeMapProvider (HTMP) files. Once the files locations have been input and the host consumed, you can use AutoProxyGen to specify entry points and exclude items, then save these specification in an input file. AutoProxyGen can be incorporated in build events and includes a basic VSTA v 2 integration to allow for customizations.
What is ProxyGen?
- Tool included in the SDK to create the proxy and host type map provider files necessary for a VSTRA v 2.0 integration
How does ProxyGen work?
- The integrator first designs an OM in their host application and builds the exe, dll, or tlb to expose.
- Through the command prompt enter commands to expose the host application to ProxyGen and create a descriptor file.
- Modify the xml descriptor file specifying entry points and excluded items. Other changes may be necessary.
- Through the command prompt enter commands to expose the updated descriptor file and create the proxy and host type map provider files.
What are some problems with ProxyGen that AutoProxyGen fixes?
- ProxyGen requires manual steps to create the descriptor file, update it, and use it to create the proxy and host type map provider files. AutoProxyGen can do all of these in a build event, through a single command, or through a GUI.
- There are known bugs with ProxyGen including:
- Methods, properties, and events not marked as excluded being excluded
- Structs are created as classes
- Inheritance issues with COM object models
- AutoProxyGen includes workarounds for the first bug, items not marked as excluded are excluded, it automatically excludes structs to prevent them from being created as classes for the 2nd bug, and includes a basic VSTA integration which allows add-ins to be used to correct the inheritance issue in the 3rd bug.
- Many hosts require changes to the descriptor and proxy files which must be repeated every time the host changes. AutoProxyGen includes a basic VSTA integration so add-ins may be used to automate these repetitive changes.
The user enters file locations and selects "Consume Host". AutoProxyGen creates and runs the 1st ProxyGen command which consumes the host application and creates the descriptor file. Once the descriptor file is created or the user indicates to use an existing file, the descriptor file is consumed and all types and ProxyGen messages are displayed. Once the user has finished specifying entry points and excluded items, the user selects "Create Proxy". The descriptor file is then updated with the entry points and excluded items, then the 2nd ProxyGen command, which consumes the descriptor file and creates the proxy and HTMP files, is run.
This can be automated by selecting "Create Input File" once all file locations, entry points and excluded items are specified. Once an input file has been created it can be run by selecting "Consume Input File" or through the command prompt or build event.
Further customizations are possible through VSTA. AutoProxyGen exposes only file locations and 4 events indicating when files have been created.
Only the entry points and excluded items specified through the AutoProxyGen GUI or input file will be excluded or marked as an entry point in the proxy and HTMP files.
Steps:
- 1) Enter file locations.
- 2) Select "Consume Host".
- 3) Specify entry points and excluded items.
- 4) Select "Create Proxy".
Automate AutoProxyGen with input files:
- Once step 3 above is complete, select "Create Input File".
- Use the input file by selecting "Consume Input File" to automate steps 1-4 above.
- Use the input file by running a command through the command prompt.
- Use the input file in a build event (see section on "Using AutoProxyGen as a Build Event").
Customize AutoProxyGen with VSTA add-ins:
- Register AutoProxyGen as a VSTA host by running the included setup file.
- Create and build add-ins.
- Run AutoProxyGen as normal (GUI or build event).
To allow for customizations AutoProxyGen includes a basic VSTA v 2.0 integration. The object model includes only the file locations and events triggered by files being created or updated.
The templates included use the same post build event as the ShapeAppSamples included with the VSTA v 2.0 SDK which moves the add-in assemblies to %MyDocuments%\AutoProxyGen\AppAddIns. All add-in assemblies found at this location are loaded.
To use VSTA with AutoProxyGen build the solution file (AutoProxyGen.sln) and run the included setup file (SetupAutoProxyGen.js).
Events:
- BeforeConsumeHostEvent- Raised prior to executing the 1st ProxyGen command.
- DescriptorFileCreatedEvent- Raised once the descriptor file ready to be consumed. Triggered if the file is created with ProxyGen or if an existing file is used.
- DescriptorFileUpdatedEvent- Raised once the descriptor file is updated with entry points and excluded items but prior to running it through ProxyGen.
- ProxyfileCreatedEvent- Raised once the proxy and HTMP files have been created.
A sample add-in is included which implements a workaround for COM hosts, correcting their inheritance.
If using VSTA add-ins to work directly with the descriptor file it is strongly recommended that your use the VB.Net template because it includes intellesence for the ProxyGen schema. This feature is not available in C#.
AutoProxyGen may be used from the command line or as a build event. An input file created by AutoProxyGen is required for this and is the only parameter. Within this input file all file locations, entry points, and excluded items are specified.
When using AutoProxyGen as a build event keep in mind that the HTMP will be created when run. If this file is contained within the host project the host will need to be re-built. A possible work around for this is to build the host twice: first using an input file with the final location for the HTMP (this will move the HTMP into the solution for the second build), the second build should use an input file without the final location for the HTMP. The HTMP only needs to be updated if a new type is being exposed to VSTA.
Example command:
AutoProxyGen /i:"C:\ShapeAppSamples\ShapeAppBasicCSharp\AutoProxyGen_Input.xml"
*Notice the input command is "/i:" immediately followed by the file location with no space.
All excluded methods, properties, and events (MPEs) are moved to the end of the parent type automatically to work around a ProxyGen bug which excludes additional MPEs after encountering an excluded MPE.
There is an "Exclude All Structs" option available which automatically excludes all structs, to work around a ProxyGen bug which creates classes in the proxy file for structs in the host. Once the proxy is generated with all structs included, the structs must be manually added to the proxy project. For more information on this please see the on-line VSTA 2.0 SDK (http://msdn.microsoft.com/en-us/library/cc747850.aspx).
The sample add-in included demonstrates how to correct the inheritance for COM hosts. ProxyGen does not expose events for COM objects without adding the implementation of the event interfaces.
- Base types- ProxyGen does not support external base types an error that the type is not remotable. An easy workaround for this is to exclude the base type. This will allow the type to inherit MarshalByRefObject and pass through the proxy layer; however, it will not pass with its base type functionality. To expose it with this functionality explicitly implement the methods, properties, and events of the base type to expose.