Erstellen eines Visual Studio Add-In Projektes für Visual Studio 2005/2008

Bei meinem letzten Vortrag zur Visual Studio Add-In Entwicklung, habe ich beim Treffen der .NET User Group Franken im Oktober 07, einiges zur allgemeinen Erweiterung und Automatisierung von Visual Studio gezeigt. Neben vielen anderen interessanten Punkten habe ich auch das Erstellen von Project- und Project-Item-Templates gezeigt. Dabei kann man mit Hilfe von Visual Studio 2005 eigene Templates für Projects oder Templates für einzelne Items eines Projects erstellen. Der Benefit für mich als Add-in Entwickler ist die einmalige Erstellung eines auf meine Bedürfnisse angepasstes Add-In Projects, dass ich bei nachfolgenden Add-In Projects immer wieder verwenden kann. Was macht aber ein Project zu einem Visual Studio Add-in Project? Oder besser ausgedrückt:

Was benötigt man zur Erstellung eines Visual Studio Add-ins?

Neun Schritte sind notwendig um ein Add-in für Visual Studio (ab Version 2005) zu erstellen. Dabei wird nicht davon ausgegangen das Controls oder andere UI-Elemente für die Visual Studio IDE erstellt werden sollen. Die dafür notwendigen Schritte, werden in einem Weiteren Blogeintrag erläutert.

1. Erstellen Sie ein einfaches ClassLibrary Project mit Visual Studio (2005/2008). Speichern Sie dieses Project in einem Verzeichnis Ihrer Wahl ab und legen Sie in den Projekteigenschaften einen aussagekräftigen Namespace für Ihr Add-in fest. Für dieses Beispiel wird der Namespace „CustomVisualStudioAddIns“ angenommen. Ändern Sie auch den automatisch eingefügten Namesspace in der Code Datei Class1.cs. Benennen Sie nun noch die automatisch generierte Klasse „Class1“ in „Connect“ um. Zur besseren Übersicht sollten Sie auch die automatisch generierte Code Datei von Class1.cs in Connect.cs umbenennen. Natürlich könnten Sie die Klasse oder die C# Code Datei benennen wie es Ihnen beliebt. Auch „HansDampf“ wäre möglich. :-)
   Die meisten Beispiele im Netz benutzen aber den Namen Connect für diese Klasse und eine mögliche Suche nach weiteren Beispielen könnte somit einfacher ausfallen.
   
2. wechseln Sie nun in die Eigenschaftenseite Ihres Add-in Projects und wechseln Sie (falls nicht schon offen) in den Bereich „Application“. Öffnen Sie hier über den Button „Assembly Information …“ den Assembly Information Dialog. Setzen Sie das Häkchen bei „make Assembly COM-Visible“. Da im Herzen von Visual Studio 2005/2008 immer noch COM schlägt, ist es notwendig Ihre Add-in Assembly COM-Visible zu machen. Mehr Informationen zum Thema COM-Visible finden Sie hier und hier.
   
3. Wechseln Sie nun in den Solution Explorer von Visual Studio um hier die notwendigen Referenzen zu setzen. Klicken Sie mit der rechten Maustaste auf Ihr Add-In Project und wählen Sie hier „Add Reference“. Im darauf erscheinenden Dialog wählen Sie in unter der Registerkarte .NET die Referenzen auf die Assemblies „EnvDTE“, „EnvDTE80“ und „Extensibility“.
   
4. Damit Visual Studio ab Version 2005 überhaupt von der Existenz Ihres Add-ins etwas erfahren kann, müssen Sie es bei Visual Studio registrieren. Bis zur Visual Studio Version .NET 2003 waren dazu manuelle Einträge in der Windows Registry notwendig. Natürlich konnte man sich diese Arbeit bei der Verteilung vom Installer des Add-ins abnehmen lasse. Trotzdem sind solche Eingriffe in die Windows Registry immer mit einem gewissen Risiko verbunden und gestalten sich ab Windows Vista noch schwieriger oder gar unmöglich. Dieses Vorgehen wurde durch "*.AddIn" Registrierungsdateien abgelöst. Diese "*.AddIn" Dateien sind XML-basierend und benutzen das XML-Schema „xmlns=http://schemas.microsoft.com/AutomationExtensibility“. Mit der Anbindung an dieses Schema erhalten Sie von Visual Studio ein Intellisense und eine Autovervollständigung der AddIn-Tags. In Listing1 sehen Sie den Aufbau einer AddIn Datei, die alle Pflichtelemente enthält. Die Beschreibung der einzelnen Pflicht und optionalen AddIn Tags erhalten Sie hier in der MSDN von Microsoft. Es ist also ausreichend wenn Sie Ihr Visual Studio Add-in Project mit einer neuen XML Datei verknüpfen und deren Endung (Extension) in „.AddIn“ ändern. Der wichtigste Aspekt bei einer AddIn Datei ist der entsprechende Speicherort. Visual Studio schaut in bestimmten vordefinierten Verzeichnissen auf Ihrem PC Ausschau nach diesen *.AddIn Dateien. Wo Visual Studio nach diesen Dateien nachschaut, können Sie unter ToolsOptions im Bereich „Add-In/Macros Security“ nachsehen. Hier haben Sie auch die Möglichkeit neue Pfade hinzuzufügen oder existierende Einträge zu löschen. Natürlich nur dann, wenn Sie auch die nötigen Rechte auf Ihrem PC besitzen. Nun können Sie nicht für jedes Projekt einen neuen Pfad hinzufügen. Legen Sie sich deshalb am einfachsten einen eigenen Pfad, für Ihre eigenen *.AddIn Dateien an. Wählen Sie den Pfad möglichst flach. Das wird Ihnen unnötiges Navigieren in die Tiefen Ihrer Verzeichnisse ersparen. Wenn Sie sich zum Beispiel für den Pfad „C:\MyVSAddInFiles“ entscheiden, dann tragen Sie diesen Pfad auch im oben genannten Dialog der Visual Studio Optionen ein. Besonders wichtig ist das Vorgehen beim Erstellen einer solchen *.AddIn Datei in Ihrem Add-in Project. Wenn Sie über das Kontextmenü Ihres Add-in Projects ein neues Item als XML Datei hinzufügen, wird Ihnen Visual Studio die XML Datei im Verzeichnis Ihres Add-in Projects abspeichern. Das ist natürlich weniger Hilfreich wenn Visual Studio nicht in diesem Verzeichnis nach *.AddIn Dateien sucht. Erstellen Sie also eine neue XML Datei in dem Verzeichnis, in dem auch Visual Studio nach *.AddIn Dateien schaut und ändern sie die Dateiendung (Extension) in „*.AddIn“ um. Öffnen Sie nun das Kontextmenü Ihres Visual Studio Projects im Solution Explorer und wählen Sie den Eintrag „Add Existing Item …“. Wechseln Sie in dem sich geöffneten Dialog in das entsprechende Verzeichnis Ihrer zuvor erstellten „*.AddIn“ Datei und fügen Sie die Datei als Link Ihrem Projekt hinzu. Die Option „Add as Link..“ finden sie unter dem kleinen schwarzen Dreieck, das sich neben dem Button „Add“ befindet. Würden Sie hier nur „Add“ auswählen, würde Ihnen Visual Studio eine Kopie der Datei in das Verzeichnis Ihres Visual Studio Projektes legen und sie würden nie die Datei bearbeiten, auf die Visual Studio schaut.
   
   
   
5. Damit Visual Studio 2005/2008 den Einsprungspunkt in Ihren Add-in findet, müssen sie nun der Klasse „Connect“ das Interface „IDTExtensibility2“ hinzufügen. Damit implementiert Ihre Klasse „Connect“ nun fünf neue Methoden. Einstiegsmethode für Visual Studio ist die Methode „OnConnection“. Hier werden an das Add-in alle nötigen Instanzen übergeben. So auch die Instanz des Visual Studio Erweiterungs-Model. Beginnen Sie in der Methode Connect mit der Initialisierung des DTE2-Objects und dem AddIn-Object.
   
6. In der Methode „OnConnection“ sollten sie eine „Switch“ Anweisung verwenden um auf den ConnectMode für Ihr Add-in angepasst reagieren zu können. Es ist sehr wichtig zu wissen in welchem ConnectMode Ihr Add-In geladen wurde. Werden Sie zum Beispiel mit dem ConnectMode „ext_cm_UISetup“ geladen, haben Sie die Möglichkeit alle Ihre Commands und Controls in Visual Studio zu integrieren. Sie sollten dies auch nur unter diesem ConnectMode tun. Versuchen Sie Ihre Commands und dessen Controls in einem anderen ConnectMode immer und immer wieder zu initialisieren, dann wird Sie Visual Studio mit einer nicht abzufangenden COM-Exception aus Visual Studio verabschieden. Visual Studio schreibt sich alle initialisierten Commands und dessen Control in eine eigene Datei weg. Darum müssen und sollten Sie sich nur ein Mal ein Command und dessen Control in Visual Studio integrieren. Mehr zu den Bedeutungen der einzelnen ConnectMode, erfahren Sie hier.
   
7. Haben Sie über Ihre zum Add-in gehörende *.Add-in Datei an Visual Studio die Anweisung gegeben, das es Ihr Add-in mit dem Start von Visual Studio laden soll, dann sollten Sie der Methode „OnStartupComplete“ besondere Aufmerksamkeit widmen. Versuchen Sie mit dem Start von Visual Studio im ConnectMode „ext_cm_Startup“ innerhalb der Methode „OnConnection“ auf UI-Elemente von Visual Studio zuzugreifen, dann kann es Ihnen sehr schnell passieren dass Sie von Visual Studio auf direktem Wege mit einer COM-Excepion aus Visual Studio rausschmeißt. Nutzen Sie deshalb im ConnectMode „ext_cm_Startup“ die Methode „OnStartupcomplete“. Ruft Visual Studio diese Methode auf, können Sie sich gewiss sein dass Visual Studio vollständig geladen wurde und Sie können nun auf andere UI-Elemente (zum Beispiel den Solution Explorer) zugreifen.
   
8. Ihr Add-in kann auf mindestens drei verschiedene Weisen aus Visual Studio geladen werden.
   
   a. Über eine nicht händelbare COM-Exception

b. Über den Add-In Manager von Visual Studio
c. Durch das beenden von Visual Studio selbst

Sollten Sie in Ihrem Add-in Event Handler mit „+= new“ referenziert haben, dann müssen Sie sich beim Entladen Ihres Add-ins auch wieder von den Handlern mit „-= new“ abnabeln. Tun Sie das nicht, kann Ihnen diese Unachtsamkeit Visual Studio mit einer weiteren COM-Exception danken und sie endgültig aus Visual Studio entladen. Wenn ein Benutzer von Visual Studio Ihr Add-in über den Add-in Manager aus Visual Studio lädt, dann wird Visual Studio in Ihrem Add-in die Methode „OnDisconnection“ aufrufen. Wird Visual Studio komplett beendet, wird ach wenn das Beenden von Visual Studio abgebrochen werden kann, in Ihrem Add-in die Methode OnBeginShutdown aufgerufen und danach die Methode „OnDisconnection“. Beachten Sie also, dass Sie in jedem Falle die Aufräumarbeiten in der Methode „OnDisconnection“ aufrufen. An die Methode „OnDisconnection“ übergibt Visual Studio einen „DisconnectMode“. Stellen Sie über dieses Methode Argument fest, warum Visual Studio Ihr Add-in entladen hat. Sollte Visual Studio diese Methode mit dem DisconnectMode „ext_dm_UISetupComplete“ aufrufen, müssen Sie natürlich keine Eventhandler aufräumen. Ihr Add-i wurde nur zum Initialisieren Ihrer Commands und Command-Controls aufgerufen und wird nun direkt von Visual Studio entladen.


9. Um Ihr Visual Studio Add-in nun noch debuggen zu können, müssen Sie in den Eigenschaften Ihres Add-in Projects noch zwei kleine Einstellungen vornehmen. Setzen Sie im Bereich „Debug“ die Start Action auf „start external Application“ und tragen sie den Pfad „<Laufwerk>\Program Files\Microsoft Visual Studio 8\Common7\IDE\devenv.exe“
   oder für VS2008
   „<Laufwerk>\Program Files\Microsoft Visual Studio 9\Common7\IDE\devenv.exe“
   ein. Damit wird Visual Studio als Ihr Host gestartet. Setzen Sie nun noch den Pfad für das Arbeitsverzeichnis der externen Applikation (Visual Studio) die beim Debuggen gestartet werden soll. Geben Sie dazu unter „Working directory“ den Pfad
   „<Laufwerk>\Program Files\Microsoft Visual Studio 8\Common7\IDE\“
   oder für VS2008
   „<Laufwerk>\Program Files\Microsoft Visual Studio 9\Common7\IDE\“ an.

Zum Abschluss wäre noch der Hinweis wichtig, das Sie es nicht verpassen sollten, nach beendigung Ihrer Arbeiten am Visual Studio Add-in auch die entsprechende *.AddIn Datei wieder unscharf zu schalten. Damit meine ich das Ändern der Dateiendung (Extension) auf *-AddIn_. Andernfalls wird beim nächsten Start dieses Add-in von Visual Studio wieder versucht zu laden. Sollte es noch einen kleinen Bug in Ihrem Add-in geben, würde hier nur eine unnötige Fehlermeldung von Visual Studio ausgegeben werden.

<?xml version="1.0" encoding="utf-16" standalone="no"?>
<Extensibility xmlns="http://schemas.microsoft.com/AutomationExtensibility">
<!--Für Visual Studio 2005-->
<HostApplication >
<Name>Microsoft Visual Studio</Name>
<Version >8.0</Version>
</HostApplication>

<!--Für Visual Studio 2008-->
<HostApplication >
<Name>Microsoft Visual Studio</Name>
<Version >9.0</Version>
</HostApplication>
<Addin >
<FullClassName>CustomVisualStudioAddIns.Connect</FullClassName>
<Assembly>..\src\BuildOutput\debug\VisualStudioAddIn.dll</Assembly>
<LoadBehavior>1</LoadBehavior>
</Addin>
</Extensibility>
Listing1

HTH

TOM_MUE

Technorati-Tags: VS Add-in Entwicklung,VS2005,VS2008