VSTA Documents

MSDN: VSTA 2.0 Brings Power to the People

Gary — Wed, 01 Dec 2010 20:28:09 GMT

Author: Gary Depue

Published: MSDN Magazine March 2008

Autodesk Revit VSTA Case Study

dschneid — Fri, 23 Jan 2009 14:47:33 GMT

A case study outlining Autodesk Revit's integration of VSTA and the benefits derived from the integration of VSTA into Revit.

HostItemProvider item templates for VSTA v 2

Melody — Thu, 20 Mar 2008 19:49:17 GMT

There are now item templates available for the VSTA v 2 HostItemProvider in C# and VB.Net. These templates are compatible with Visual Studio 2005 and 2008.

To use these templates:

1) Copy the zip files into %Program Files%\Microsoft Visual Studio %version%\Common7\IDE\ItemTemplates\[CSharp,VB.Net]\1033 .

2) Run devenv /setup from the Visual Studio command prompt.

3) Add the HostItemProvider to the project.

4) Change the type "YourEntryPointType" to match your entry point type(s).

5) Change the parameter inYourEntryPointType and variable mYouEntryPoinType to match your entry point type. (optional)

These templates can be modified to work with more than one entry point type or for use with the Dynamic Programming Model. See the ShapeAppDynamicProgrammingModelCSharp for details on these modifications.

using System;

using System.Collections.Generic;

using System.Text;

using System;

using Microsoft.VisualStudio.Tools.Applications.Runtime;

namespace $namespace$

{

/// <summary>

/// Implementation class for IHostItemProvider interface.

/// Used by the AddIns to access the Host Object of the

/// application they are running on.

/// </summary>

internal class HostItemProvider : IHostItemProvider

{

#region Constructors

/// <summary>

/// Initializes a new instance of the <see cref="HostItemProvider1"/> class.

/// </summary>

/// <param name="inYourEntryPointType">The application to load AddIns for.</param>

public HostItemProvider1(YourEntryPointType inYourEntryPointType)

{

this.mYourEntryPointType = inYourEntryPointType;

}

#endregion //Constructors

#region IHostItemProvider Members

/// <summary>

/// Gets the host object.

/// </summary>

/// <param name="primaryType">The type of the Host Object to get.</param>

/// <param name="primaryCookie">Not used.</param>

/// <returns>The HostObject of type <paramref name="primaryType"/>.</returns>

/// <exception cref="ArgumentOutOfRangeException"><paramref name="primaryType"/> is not <see cref="inYourEntryPointType"/></exception>

public object GetHostObject(Type primaryType, string primaryCookie)

{

//Check if primaryType is supported.

if (primaryType == typeof(YourEntryPointType))

{

return this.mYourEntryPointType;

}

else

{

throw new ArgumentOutOfRangeException("primaryType != " + typeof(YourEntryPointType));

}

#endregion //IHostItemProvider Members

#region Private Fields

private YourEntryPointType mYourEntryPointType;

#endregion //Private Fields

}

Imports System

Imports Microsoft.VisualStudio.Tools.Applications.Runtime

''' <summary>

''' Implementation class for IHostItemProvider interface.

''' Used by the AddIns to access the Host Object of the

''' application they are running on.

''' </summary>

Public Class HostItemProvider : Implements IHostItemProvider

'Private Fields

Private mYourEntryPointType As YourEntryPointType

''' <summary>

''' Initializes a new instance of the <see cref="HostItemProvider"/> class.

''' </summary>

''' <param name="inYourEntryPointType">The application to load AddIns for.</param>

Public Sub HostItemProvider(ByVal inYourEntryPointType As YourEntryPointType)

Me.mYourEntryPointType = inYourEntryPointType

End Sub

''' <summary>

''' Initializes a new instance of the <see cref="HostItemProvider"/> class.

''' </summary>

''' <param name="inYourEntryPointType">The application to load AddIns for.</param>

Public Sub New(ByVal inYourEntryPointType As YourEntryPointType)

Me.mYourEntryPointType = inYourEntryPointType

End Sub

''' <summary>

''' Gets the host object.

''' </summary>

''' <param name="primaryType">The type of the Host Object to get.</param>

''' <param name="primaryCookie">Not used.</param>

''' <returns>The HostObject of type <paramref name="primaryType"/>.</returns>

''' <exception cref="ArgumentOutOfRangeException"><paramref name="primaryType"/> is not <see cref="YourEntryPointType"/></exception>

Public Function GetHostObject(ByVal primaryType As System.Type, ByVal primaryCookie As String) As Object Implements Microsoft.VisualStudio.Tools.Applications.Runtime.IHostItemProvider.GetHostObject

'Check if primaryType is supported

If primaryType Is GetType(YourEntryPointType) Then

Return Me.mYourEntryPointType

Else

Throw New ArgumentOutOfRangeException("primaryType is Not " & GetType(YourEntryPointType).ToString())

End If

End Function

End Class

HostTypeMapProvider in VB.Net

Melody — Mon, 10 Mar 2008 15:21:58 GMT

ProxyGen outputs the Proxy and HostTypeMapProvider files in C#. For anyone interested in using a VB.Net HostTypeMapProvider, here is a download to help with this.

Included in this download:
   Template- the template is a HostTypeMapProvider in VB.Net without types.
   Macro- translates C# canonicalToTypeName.Add and typeToCanonicalName.Add statements from the HostTypeMapProvider created by ProxyGen to VB.Net

Instructions:
   Add the HostTypeMapProvider template to the host VB.Net project.
   Copy the C# canonicalToTypeName.Add and typeToCanonicalName.Add statements from the HostTypeMapProvider created by ProxyGen.
   Paste the statements into the New method.
   Run the macro.

For your convience, the template and macro can be copied from here:

'This file works as a template for VB HostTypeMapProviders.

' Copy and paste the types generated by ProxyGen into the

' constructor below.

' Then run the HTMProvider_TranslateTypesToVB macro with

' this file selected.

Public Class HostTypeMapProvider : Implements Microsoft.VisualStudio.Tools.Applications.Runtime.ITypeMapProvider

Dim typeToCanonicalName As System.Collections.Generic.Dictionary(Of System.Type, System.String) = System.Collections.Generic.Dictionary(Of System.Type, System.String)()

Dim canonicalToTypeName As System.Collections.Generic.Dictionary(Of System.String, System.Type) = System.Collections.Generic.Dictionary(Of System.String, System.Type)()

Friend Sub New()

'add types here to translate.

'Run HTMProvider_TranslateTypesToVB macro with this doc selected

End Sub

Public Function GetCanonicalNameForType(ByVal type As System.Type) As String Implements Microsoft.VisualStudio.Tools.Applications.Runtime.ITypeMapProvider.GetCanonicalNameForType

'default fetch from dictionary

If typeToCanonicalName.ContainsKey(type) Then

Return typeToCanonicalName(type)

End If

Return Nothing

End Function

Public Function GetTypeForCanonicalName(ByVal canonicalName As String) As System.Type Implements Microsoft.VisualStudio.Tools.Applications.Runtime.ITypeMapProvider.GetTypeForCanonicalName

'defualt fetch from the dictionary

If canonicalToTypeName.ContainsKey(canonicalName) Then

Return canonicalToTypeName(canonicalName)

End If

Return Nothing

End Function

End Class

Option Strict Off

Option Explicit Off

Imports System

Imports EnvDTE

Imports EnvDTE80

Imports EnvDTE90

Imports System.Diagnostics

Public Module HTMProvider_TranslateTypesToVB

'Translates the types found in a HostTypeMapProvider from C# to VB

Public Sub HTMProvider_TranslateTypesToVB()

'make syntax changes

FindReplaceAll(";", "")

FindReplaceAll("<", "( Of ")

FindReplaceAll(">", ")")

FindReplaceAll("typeof", "gettype")

'correct the formatting

DTE.ExecuteCommand("Edit.FormatDocument")

End Sub

'replaces all occurences of the find string with the replace string

Private Sub FindReplaceAll(ByVal inFind As String, ByVal inReplace As String)

DTE.Find.FindWhat = inFind

DTE.Find.ReplaceWith = inReplace

DTE.Find.Target = vsFindTarget.vsFindTargetCurrentDocument

DTE.Find.MatchInHiddenText = True

DTE.Find.PatternSyntax = vsFindPatternSyntax.vsFindPatternSyntaxLiteral

DTE.Find.Action = vsFindAction.vsFindActionReplaceAll

End Sub

End Module

How To Integrate VSTA 2.0 PowerPoint Slides from MSDN Webcast

Gary — Tue, 29 Jan 2008 14:53:32 GMT

PowerPoint Slides (with presenters notes included) from January 23 2008 MSDN Webcast

Known Issues with the VSTA v 2 CTP Release

Melody — Tue, 11 Dec 2007 23:17:10 GMT

Foreword:

The information in this document should be used as a supplement to the SDK included with the VSTA v 2 CTP release. This release is not the final version of VSTA v 2. The final version is expected in February of 2008. Between now and the final release changes will be made.

ProxyGen:

ProxyGen is still in active development. Some known issues with the CTP release include a lack of warnings when a code containing class is skipped (due to nesting or special naming) and inconsistent handling of generics. Please see our ProxyGen v 2 CTP ReleaseSupplement for more details

SDK:

The SDK has many circular and broken links.

The SDK section "Proxies for Managed Assemblies" states that static types and members are not supported. This is incorrect, static types and members are supported. For more information on static types and members please see the section "Architecture of Generated Proxy Code".

ShapeApp Walkthroughs:

The Walkthroughs are still under development. The walkthrough sections associated with a basic or loose integration (taking ShapeAppCSharp to ShapeAppBasicCSharp) have errors in several of the CopyCode sections. These errors tend to be minor and easy to fix.

The walkthrough sections associated with an advanced integration (taking ShapeAppBasicCSharp to ShapeAppMacroRecrodingCSharp) do not work. Once a working walkthrough is available we will let you know.

ShapeAppSamples:

Be sure to run the setup files for each sample prior to running.

The samples included in the CTP release are for Visual Studio 2008. Opening these projects in Visual Studio 2005 is not suggested.

If Save or SaveAs is selected from the file menu when no document (collection of drawings- this is new to the v2 samples) is open a NullReferenceException will be thrown.

The sample ShapeAppBasicCSharp builds with a warning about the AddInAdapter.

The sample ShapeAppBasicMFC builds with warnings about the AddInAdapter and command line D9305.

The sample ShapeAppMacroRecordingCSharp has known issues and is still under development. Recording and running macros may not work and the sample may display a "Delay Notification" warning asking you to send information to Microsoft on what you were doing when you got this message. This message appears when the macro project fails to build, the build failure message may be displayed in the background. Also note, when this sample is closed Loader Lock may be detected. You can stop the application by selecting OK or Cancel from the Loader Lock warning and then stopping debugger through Visual Studio. Once a more functional version of this sample is available we will let you know. In the mean time, if you wish to provide feedback on the scenario in which you received the Delay Notification warning requesting you to send information please do so here: http://www.summsoft.com/forums/738/ShowThread.aspx#738

ProxyGen v 2 CTP Release Supplement

Melody — Thu, 06 Dec 2007 16:59:39 GMT

ProxyGen v 2

CTP Release

Supplement

Table of Contents

I. Foreword

II. Introduction

III. Overview

IV. How the Proxy file works

V. How the Host Type Map file works

VII. ProxyGen v 1 Issues Status Update

VIII. ProxyGen and Generics

VIII.1 ProxyGen v 1 and Generics

VIII.2 ProxyGen v 2 and Generics

VIII.2.1 I nheriting from a generic type

IX. ProxyGen v 2 Changes

IX.1 Nested Types

IX.2 Delegates

IX.3 Static Properties and Methods

IX.4 Custom Exceptions

IX.5 Application and Library names

IX.6 Indentation

IX.7 Forms, WPF, and ProxyGen

IX.8 Non-Public classes, structs, properties, and methods

X. ProxyGen v 2 with Visual Basic

X.1 The Visual Basic warning in ProxyGen output

X.2 Interfaces that declare types

X.3 Special Namespaces

X.4 Modules

X.5 Optional Parameters

XI. ProxyGen v 2 with C#

XII. ProxyGen v 2 with COM

XIII. Appendix

XIII.1 References

XIII.2 Upates and Changes

I. Foreword

II. Introduction

ProxyGen is a tool used during VSTA integration to generate the proxy layer through which the host and add-ins communicate. Three files are produced by ProxyGen including the descriptor, host type map and proxy. The descriptor file is created using the host object as input and is an xml description of the host. The descriptor file is manually edited to include at least one add-in entry point. Once updated, the descriptor file is used as input to create the host type maps and the proxy files. The host type map includes all public types specific to the host that will be passed through the proxy layer. The proxy file is used by add-ins to communicate with the host.

III. Overview

This guide gives information on specific topics relating to ProxyGen version 1 and the CTP release of version 2. A basic level of understanding of ProxyGen and VSTA integration is assumed. For more information or clarification on any topics please refer to the SDK. The SDK documentation for ProxyGen v 2 is detailed and much more in-depth than it was for ProxyGen v 1.

IV. How the Proxy file works

The SDK offers the following explanation of the proxy layer:

“A proxy is a type that represents the add-in's view of a type in the host object model. Rather than using host types directly, add-in developers instead use proxy types. This layer of abstraction provides a number of benefits, including the ability to modify the object model that your application exposes to add-ins without changing or recompiling the host object model itself.”

“A proxy is a type that serves as an intermediary between an add-in and a type in the host object model. When the add-in developer writes code to automate the host application, their add-in project references the proxy assembly for the application, and they use the proxy types as if they were the actual host types. However, only a few proxy types contain code that is executed at run time; most proxy types are just blueprints that Visual Studio Tools for Applications uses to call into the actual host types.”

ProxyGen v 2 creates much different proxies than were generated by ProxyGen v 1. In ProxyGen v 2 each exposed class from the host application has one or two (if the class is and add-in entry point) corresponding classes in the proxy layer. Along with these two types of classes is one additional class, the ProxyServices.Helper class which is used by static methods.

The first corresponding class has the same name as the class in the host application and contains non-implemented properties and methods for non-static and non-constructor methods in the host application. Static methods and properties in the host class are fully implemented here, and available to add-ins through this class. Constructors found in the proxy are for internal use only (proxies do not support the “new” operator). Calls to the non-implemented methods should resolve themselves prior to the reaching the NotImplementedException in the non-implemented methods.

The second corresponding class is for add-in entry points and has the same name as the class in the host application appended with “EntryPoint”. These classes contain code to allow communication between the add-in and host and for are fully implemented. These implemented methods are similar to the methods produced by ProxyGen v 1. Static methods and properties are not included in these entry point classes; instead, they are resolved using the first corresponding class and the ProxyServices.Helper class.

For more information on how the proxy file is set up, please see the “Architecture of Generated Proxy Code” in the SDK.

V. How the Host Type Map file works

The SDK offers the following explanation of host type maps:

“One of the required services that you must implement in the host application is a type map provider. Visual Studio Tools for Applications uses type maps to determine how to convert types between the object model of your host application and proxy types used by add-ins. A type map is a data structure that associates Type objects, which describe the types in the host application, with canonical names that uniquely identify each type. The type map provider is a class that associates the types in the host object model with canonical names.”

The use of host type maps in VSTA v 2 is a major improvement and one of the components that allows the dynamic programming model. The host type maps are only contained on the host side, not the proxy. The host type map file is automatically generated by ProxyGen when a proxy file is generated using the “/c” command and has the same name as the proxy, appended with “.HostTypeMap”.

The host type map file uses two methods to allow types to pass between the host and add-ins: GetCanonicalNameForType and GetTypeForCanonicalName. The GetCanonicalNameForType method is used to get the CanonicalName for a type passed from the host to the add-in. The GetTypeForCanonicalName method is used to convert the proxy type to a host side type when a type is passed from the add-in to the host. Unlike the type infrastructure manager in ProxyGen v 1, all types contained in the host type map are viewable. This allows the programmer to see what types are being passed between the proxy and add-in and what types are available. This eliminates the vagueness of the KeyNotFoundException.

For more information on host type maps, please see the “Mapping Host Types to Proxy Types” and “Walkthrough: Modifying an Application to Load Add-Ins” sections in the SDK.

VI. Commands

The commands for ProxyGen v 2 are very similar to the commands for ProxyGen v 1. The most notable difference is the proxy and host type map files may only be created together and use the descriptor file as input, not the host application. The host type map will have the same file name as the proxy file with “.HostTypeMap” appended prior to the file extension. Namespace specifications work for the proxy and host type map files, not the descriptor file. As before, the command /f forces files to be overwritten and may be used with any command.

Some common errors when entering commands is to omit the space before a command or to use the “/o” command instead of the “/i” command when generating the proxy and host type map files. When command errors occur ProxyGen will output the following error:

An unrecoverable error was encountered during processing.

Exception has been thrown by the target of an invocation.

This may have been caused by earlier errors.

ProxyGen.exe Information: 0 : Finished

Sample commands.

The following are the most commonly used commands. These sample commands use a host library, C:\Host.dll, to create a descriptor file, C:\OM.xml, a proxy file, C:\Proxy.cs, and a host type map, C:\Proxy.HostTypeMap.cs. The namespace in the proxy file is changed to “MyNamesapce”.

Command	Description
ProxyGen /l:”C:\Host.dll” /o:”C:\OM.xml”	Uses the host library (/l:”C:\Host.dll”) to output a descriptor file (/o:”C:\OM.xml”).
ProxyGen /i:”C:\OM.xml” /c:”C:\Proxy.cs”	Uses the descriptor file as input (/i:”C:\OM.xml”) to create the proxy (/c:”C:\Proxy.cs”) and the host type map (“C:\Proxy.HostTypeMap.cs”) files.
ProxyGen /i:”C:\OM.xml” /c:”C:\Proxy.cs” /n:”MyNamespace” /f	Uses the descriptor file as input (/i:”C:\OM.xml”) to create the proxy (/c:”C:\Proxy.cs”) and the host type map(“C:\Proxy.HostTypeMap.cs”) files. The proxy and host type map will have the specified namespace (/n:”MyNamespace”). Any previous proxy and host type map files will be overwritten (/f).

VII. ProxyGen v 1 Issues Status Update

VII.1 Classes marked as isExcluded=”true” are parsed. If the parser fails inside one of these classes it will not create the proxy layer code. This issue has not been fixed.

VII.2 ProxyGen outputs “+” instead of “.” for nested or derived classes. This issue is fixed.

VII.3 ProxyGen v 1 aborted if an optional parameter’s default value was null. This issue is fixed, for more information see the section in this paper on “Optional Parameters” in “ProxyGen v 2 and Visual Basic”.

VII.4 GetEnumerator functions called from an add-in (such as using foreach in a ShapeAppBasicCSharp add-in) caused an UnsafeSerializationException because the enumerator being returned was type System.Collections.Generic.List<T>.Enumerator and not Systems.Collections.IEnumerable. This issue fixed and enumeration calls such as foreach work in add-ins.

VII.5 ProxyGen terminates prematurely with an “unrecoverable error” without outputting useful error information. This happens less frequently.

VII.6 VB.Net allows interfaces to declare types. When ProxyGen v1 encountered this a descriptor file containing the interface and a non-compilable proxy could be created. In ProxyGen v 2 interfaces that declare types are not included in the descriptor file; hence, no proxy can be created for them. This issue has been fixed by disallowing interfaces that declare types. For more information see the section in this paper on “Interfaces that declare types” in “ProxyGen v 2 and Visual Basic”.

VII.7 If no entry point was specified in the descriptor file a compilable proxy could be made; however, the following error would be given when using the proxy in ProjectGen: “Invalid Assembly. This assembly is not a valid Visual Studio Tools for Applications proxy. Please ensure that it was generated by the Proxy Generation tool.” The error message for this scenario now gives better information stating that no entry point was specified and gives instructions on how to specify an entry point. This issue has been resolved by providing better error information.

VII.8 Nested classes were problematic in ProxyGen v 1. This issue has been resolved by not allowing them. Any delegates, enumerations, interfaces, and classes that appear within a class are skipped and do not appear in the descriptor, proxy or type map files. In most cases no error or warning appears, this lack of warning has been reported to Microsoft as a bug.

VII.9 ProxyGen does not support generics. In version 1 ProxyGen would output a syntax error into the descriptor file when it encountered a generic and this would carry over into the proxy file making it noncompilable. In version 2 the syntax error still appears for some generics in the descriptor file; however, no proxy or type maps may be generated until the syntax error is removed from the descriptor file. Other generics are caught by ProxyGen and do not appear in the descriptor file. Some generics produced errors and warnings, others do not. The inconsistency of errors has been reported to Microsoft as a bug. For more information see the section in this paper on “ProxyGen and Generics”.

VII.10 The proxy file generated by ProxyGen v 1 contained errors when a class in the host application derived from MarshalByRefObject. This issue has been resolved, host classes may now inherit MarshalByRefObject without any problems in the proxy.

VII.11 While ProxyGen versions 1 and 2 will create a compilable proxy for a host application that uses delegates with 5 or more parameters, these delegates will not work. In VSTA v 1, the host will throw an exception when trying to add the delegate to the type infrastructure manager. In VSTA v 2, the host will throw a System.NotSupportedException when an add-in attempts to hook up to the delegate. This issue is not fixed and there is still a limit of 4 parameters for delegates, which causes run time crashes when exceeded. This crash has been reported to Microsoft as a bug.

VII.12 ProxyGen versions 1 and 2 translates vararg attributes to a generic ‘object’ array. This is by design.

VII.13 ProxyGen v1 did not support static properties and methods. ProxyGen v 2 supports static properties and methods. For more information see the section in this paper on “Static Properties and Methods” under “ProxyGen v 2 Changes".

VII.14 In ProxyGen v 1 a vague KeyNotFoundException could be thrown with no information about the key that caused the problem and the available keys. Now any type passing between the host and add-in can be easily identified and all available types can be shown.

VIII. ProxyGen and Generics

ProxyGen does not support generics (in both version 1 and 2). The information provided in this section shows how ProxyGen reacts when generics are encountered. In ProxyGen v 1 a workaround was possible. No work around has been found for ProxyGen v 2 at this time.

VIII.1 ProxyGen v 1 and Generics

ProxyGen version 1 would produce a syntax error in the descriptor file when it encountered a generic (see code sample 1 below). This syntax error would be carried over to the proxy file. When generating the host type map file, ProxyGen would skip generics all together.

As seen in Tom Quinn’s ShapeAppAdvancedCSharpGenerics sample (ref 1) and Summit Software’s Event Sample (ref 2) these issues can be worked around by manually correcting the syntax errors in the proxy and adding the types to the type maps in both the proxy and host sides. For more information, check these resources out directly.

Code Sample 1- ProxyGen’s generics syntax error for a generic list

System.Collections.Generic.IList`1[[Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.Drawing, ShapeAppCSharp, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null]]

VIII.2 ProxyGen v 2 and Generics

ProxyGen version 2 skips some generics when creating the descriptor file; however, some generics do make it through into the descriptor file. Any generics in the descriptor file must be manually removed prior to creating the proxy and host type files. When ProxyGen encounters a generic that it will skip, while generating a descriptor file, a warning appears. A sample of this warning is below

Sample warnings:

ProxyGen.exe Warning: 0 : Warning: Property MyProperty in type MyType contains generic type information and will not be parsed.

ProxyGen.exe Warning: 0 : Warning: Method MyMethod in type MyType contains generic type information and will not be parsed.

ProxyGen.exe Warning: 0 : Warning: Event MyEvent in type MyType co

ntains generic type information and will not be parsed.

VIII.2.1 Inheriting from a generic type

When encountering a class which inherits from a generic type, ProxyGen will output an error stating that the type is not remotable because it does not have MarshalByRefObject class in its type hierarchy. In the descriptor file the class will inherit from a type similar to the syntax error produced when ProxyGen v 1 encountered a generic. The base type should be removed. If the descriptor file is left as is, ProxyGen will “trip over” the syntax error, even if the class is excluded, and no proxy or host type map file will be created.

Sample ProxyGen error when creating the descriptor file with a class that derives from a generic type:

ProxyGen.exe Error: 0 : Error: The following type is not remotable, because it does not have the MarshalByRefObject class in its type hierarchy: MyNamespace.MyType. The proxy that will be generated for this type cannot marshal calls from the add-in to the host application. To generate a usable proxy, the type must have the

MarshalByRefObject class in its type hierarchy.

Sample descriptor file output:

</BaseType>

</Class>

IX. ProxyGen v 2 Changes

IX.1 Nested Types

ProxyGen does not support nested types. Only the outermost type will appear in the descriptor, proxy, and host type map files and no warnings or errors are generated. The exception to this is interfaces with nested types which are skipped altogether, for more information on this see the section in this paper on “Interfaces that declare types” in the “ProxyGen v 2 and Visual Basic” section.

IX.2 Delegates

ProxyGen supports only delegates declared outside of classes. Any delegates that appear within a class are skipped and do not appear in the descriptor, proxy, and type map files. In the descriptor file, delegates have the additional properties newName and newNamespace, these can be ignored. Delegates with five or more parameters cause run time errors when an add-in attempts to hook up to the delegate.

IX.3 Static Properties and Methods

Static properties and methods appear in the descriptor file with the property isStatic=”true”. Non-static properties and methods do not have this property in the descriptor file. Static properties and methods are implemented in the proxy in the corresponding non-entry point classes and use the ProxyServices.Helper class to communicate remotely with the host. If the class containing the static properties and methods is an add-in entry point, the static properties and methods are not carried over to the corresponding entry point class in the proxy file. Static methods and properties must be accessed only in reference to the containing class, not to a specific instance of the class.

For example, in the ShapeAppBasicCSharp sample, the Application class has the static property MinShapeSize and static method CreateSize. For an application level add-in to set the MinShapeSize the calls must be made through the class, not through the “this” instance of the class.

Correct:

Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.Application.MinShapeSize = Microsoft.VisualStudio.Tools.Applications.Samples.ShapeApp.Application.CreateSize(100, 100);

Incorrect:

this.MinShapeSize = this.CreateSize(100, 100);

IX.4 Custom Exceptions

When ProxyGen encounters a custom exception, it is added to the descriptor file as an exception, not a class. The type for the exception will appear in the host type maps. In the proxy file some code for the exception will be generated; however, the class must be completed manually. For more information please see the SDK sections “Walkthrough: Creating a Proxy Assembly” and “Creating Proxies for Custom Exceptions”.

IX.5 Application and Library names

The originalName property of the Library in the descriptor file will match the assembly name of the host. If the assembly name starts with a number or contains spaces, ProxyGen will have a pattern constraint failure when creating the proxy and host type map files (see the error below). This error will prevent the files from being created.

ProxyGen library name error:

ProxyGen.exe Error: 0 : Error: The 'originalName' attribute is invalid - The value '1a Bad Name' is invalid according to its datatype http://schemas.microsoft.com/vsta/2008/01/ProxyGenDescriptor:name_Type' - The Pattern constraint failed. at Line:2 Position:10

ProxyGen.exe Information: 0 : Finished

ProxyGen.exe Error: 0 : 1 Errors

IX.6 Indentation

In the host type map and proxy files most code is left aligned instead of properly indented. This has been reported to Microsoft as a bug.

IX.7 Forms, WPF, and ProxyGen

In ProxyGen v 1 if a System.Windows.Forms form was exposed to the proxy, the proxy would not compile. ProxyGen v 2 produces compilable proxies when System.Windows.Forms forms are exposed so long as the appropriate reference is added; however, this type and any components based on this type can still not pass between the host and add-ins. WPF objects are handled differently by Visual Studio depending on the language. The differences in how Visual Studio handles the WPF objects carries over into VSTA and ProxyGen. When a WPF form is exposed, a non-compilable proxy can be generated. The errors found in this scenario depend on the language of the host application.

IX.8 Non-Public classes, structs, properties, and methods

If a class, struct, property or method is not marked as public it will be skipped by ProxyGen when creating the descriptor file.

X. ProxyGen v 2 with Visual Basic

X.1 The Visual Basic warning in ProxyGen output

ProxyGen output always includes the warning below. The automatically generated types referred to no longer show up in the descriptor file or cause errors, this warning may be ignored.

ProxyGen.exe Information: 0 : Note: ProxyGen does not support creating proxies for types that use generics, or that are derived from types that are defined in external assemblies. All assemblies written in Visual Basic contain automatically generated types that use these unsupported features, but you can ignore errors and warnings for automatically generated types.

X.2 Interfaces that declare types

Visual Basic.Net allows interfaces to declare types. This is not allowed by ProxyGen. When ProxyGen encounters an interface which declares a type in a host two warning will be displayed. The interface that contains a type will not appear in the descriptor file. The ProxyGen output warnings are below.

ProxyGen.exe Error: 0 : Error: Types not supported inside an interface, type Interface_name will be ignored.

ProxyGen.exe Error: 0 : Error: Types not supported inside an interface, type ClassWithinInterface_name will be ignored.

X.3 Special Namespaces

Visual Basic special namespaces (such as My.MyApplication and My.MyComputer) do not appear in the descriptor file. If code is contained in My.MyApplication, or other special namespaces, it will be skipped and no errors or warning will appear.

X.4 Modules

Modules are not supported. Any code contained within a module will be skipped by ProyxGen and not appear in the descriptor file.

X.5 Optional Parameters

ProxyGen v 2 allows optional parameters with no special handling. If the optional parameter is a numeric type (such as integer or long) or byte and the default value is Nothing, the default value will be changed to 0 in the descriptor file. If the optional parameter is type char and the default value is Nothing, an unrecoverable error will occur when generating the descriptor file, this has been reported to Microsoft as a bug.

XI. ProxyGen v 2 with C#

No C# specific issues have been found at this time.

XII. ProxyGen v 2 with COM

No COM specific issues have been found at this time.

XIII. Appendix

XIII.1 References

1) Tom Quinn’s ShapeAppAdvancedCSharpGenerics sample:

http://blogs.msdn.com/tq/archive/2006/12/05/vsta-and-generics.aspx

2) Summit Software’s Event sample:

http://www.summsoft.com/files/folders/vsta_samples/entry572.aspx

3) The VSTA v 2 CTP release SDK.

4) The VSTA v 2 CTP release ShapeApp Samples.

XIII.2 Updates and Changes

1) Revision 2.2.02 12/12/2007

Updated information regarding static methods and properties in sections IV How the Proxy file works, VII ProxyGen v 1 Issues Status Update, and IX.3 Static Properties and Methods.

If you are interested in getting access to the CTP, see the following post

VSTA vs. VBA: The Emancipation of Application Customization

Gary — Wed, 28 Feb 2007 20:51:44 GMT

VSTA gives ISVs the freedom to customize their application according to their own requirements and the requirements of their end users in the following three areas: The development environment (IDE), projects, and add-ins.

Accessing Web Services in VSTA versus VBA

Gary — Thu, 01 Feb 2007 19:48:00 GMT

Summary: Compare the use of the Office 2003 Web Services Toolkit in a VBA project with the use of Web Services directly in a VSTA project. Learn how the .Net framework’s Asynchronous Pattern for Components is used for asynchronous notification from web services in VSTA, keeping user interaction responsive.

VSTA vs VBA Wizard Comparsion and source code

Gary — Fri, 05 Jan 2007 19:59:43 GMT

In this article, we will compare the process of developing a wizard in the VSTA development environment (using VC#, Winforms and the .Net framework) with the process of developing a wizard in the VBA development environment (using VB6, and Userforms).

Includes VC# source code for New Shape Wizard to be run with the ShapeAppAdvancedCSharp sample.

VSTA vs VBA Wizard Comparison

Gary — Fri, 05 Jan 2007 19:52:35 GMT

VSTA Overview Demo

dschneid — Tue, 19 Dec 2006 16:03:51 GMT

Paul Stubbs demonstrates some of the features of VSTA in this 10 minute video.

(Click download and the file will launch in Windows Media Player)

VSTA vs. VBA

dschneid — Wed, 06 Dec 2006 15:27:45 GMT

Visual Studio Tools for Applications (VSTA) represents Microsoft's future direction in application extensibility. This document examines how VSTA leverages Microsoft Visual Studio and the Microsoft .NET Framework to support ISVs, as well as their customers and partners, by offering extensibility with control, enabling new customization scenarios, and accelerating the development of solutions for specific customers and verticals.

Managed VSTAHookup Walkthrough

Gary — Thu, 21 Sep 2006 16:26:45 GMT

Tasks illustrated in this walkthrough include:

· Creating the managed ComInterop assembly.

· Implementing a seamless debugging experience.

Walkthrough: Integrating VSTA with an Unmanaged VBA-Enabled Application

wilfis — Mon, 31 Jul 2006 16:41:04 GMT

This walkthrough demonstrates how to integrate Microsoft Visual Studio Tools for Applications (VSTA) into an existing, unmanaged VBA-enabled MFC application, for the purpose of showing VBA/VSTA side-by-side interoperability, as well as to identify some of the issues that may be faced by VBA Partners who wish to add VSTA to their VBA-enabled applications.

Overview

Tasks illustrated in this walkthrough include:

· Installation and setup of the unmanaged, VBA host application.

· Creating a proxy source DLL.

· Creating project templates.

· Loading and unloading VSTA Add-ins.

· Displaying the VSTA IDE programmatically from the host application.

· Testing a simple Add-in.