This project has moved. For the latest updates, please go here.

Tutorial11 – Weitergabe von Automation Addins

Sofern Sie bereits Erfahrungen mit der Weitergabe von eigenen Lösungen haben die auf den Interop Assemblies von Microsoft beruhen, ist die gute Nachricht für Sie das NetOffice sich auch hier nicht anders verhält und Sie bereits über das notwendige Know-How verfügen eine auf NetOffice basierende Lösungen zu verteilen.

Das folgende Tutorial geht auf die 2 gängiggen Wege ein –managed- Automation Addins für Office zu verteilen. 1.) Manuelle Weitergabe und 2.) Weitergabe als .MSI Paket.

Manuelle Weitergabe ohne Installationspaket(.msi)

Wenn Sie ein Automation Addin Projekt mit NetOffice oder den Interop Assemblies erstellen und kompilieren ist dieses Addin bereits für ihre Office Anwendung verfügbar bzw. wird geladen. Im Verlauf der Kompilierung wird die notwendige Registrierung automatisch vorgenommen. Verantwortlich ist das dafür die Projekteinstellung für COM Interop registrieren. Visual Studio ruft dafür das .NET Konsolenprogramm Regasm.exe auf und übergibt den Pfad zu ihrem Assembly. Regasm.exe analysiert nun ihr Assembly und trägt für COM relevante Einträge in die Windows-Registrierung ein. Sie können innerhalb ihres Addins 2 spezielle statische Funktionen definieren die von Regasm.exe jeweils bei der Registrierung und bei der Deregistrierung aufgerufen werden.

Sie müssen diese beiden statischen Funktionen sogar definieren da Regasm.exe ihnen nicht alle Arbeit abnimmt. Automation Addins müssen sich im Registrierungsschlüssel ihrer gewünschten Office Anwendung eintragen. Für Regasm.exe ist ihr Addin einfach nur eine COM Komponente, nicht mehr  aber auch nicht weniger. Das Eintragen der wichtigen Schlüssel für MS-Office müssen Sie also in diesen Funktionen selbst vornehmen. Betrachten wir hierzu ein kurzes Beispiel-Listing für die Register/UnregisterMethoden:

<ComRegisterFunctionAttribute()> _ 
Public Shared Sub RegisterFunction(ByVal type As Type) 
Try 
   ' add codebase value 
   Dim thisAssembly As Assembly = Assembly.GetAssembly(GetType(Addin)) 
   Dim key As RegistryKey = Registry.ClassesRoot.CreateSubKey( _ 
   "CLSID\\{" + type.GUID.ToString().ToUpper() + "}\\InprocServer32\\1.0.0.0") 
   key.SetValue("CodeBase", thisAssembly.CodeBase) 
   key.Close() 

   key = Registry.ClassesRoot.CreateSubKey( _ 
   "CLSID\\{" + type.GUID.ToString().ToUpper() + "}\\InprocServer32") 
   key.SetValue("CodeBase", thisAssembly.CodeBase) 
   key.Close()           

   ' register addin in Excel 
   Registry.CurrentUser.CreateSubKey( _ 
   "Software\Microsoft\Office\Excel\Addins\DeploymentSampleVB.Addin") 
   Dim regKeyExcel As RegistryKey = Registry.CurrentUser.OpenSubKey( _ 
   "Software\Microsoft\Office\Excel\Addins\DeploymentSampleVB.Addin", true) 
   regKeyExcel.SetValue("LoadBehavior", Convert.ToInt32(3)) 
   regKeyExcel.SetValue("FriendlyName", "DeploymentSampleVB") 
   regKeyExcel.SetValue("Description", _
"NetOffice Beispiel für die Weitergabe eines Automation Addin") regKeyExcel.Close() Catch ex As Exception Dim details As String = String.Format( _
"{1}{1}Details:{1}{1}{0}", ex.Message, Environment.NewLine) MessageBox.Show("An error occured." + details, "Error", _
MessageBoxButtons.OK, MessageBoxIcon.Error) End Try End Sub <ComUnregisterFunctionAttribute()> _ Public Shared Sub UnregisterFunction(ByVal type As Type) Try Registry.ClassesRoot.DeleteSubKey( _ "CLSID\\{" + type.GUID.ToString().ToUpper() + "}\\Programmable", False) ' unregister addin in office Registry.CurrentUser.DeleteSubKey( _ "Software\Microsoft\Office\Excel\Addins\DeploymentSampleVB.Addin")
Catch throwedException As Exception Dim details As String = String.Format( _ "{1}{1}Details:{1}{1}{0}", throwedException.Message, Environment.NewLine) MessageBox.Show("An error occured." + details, "Error", _ MessageBoxButtons.OK, MessageBoxIcon.Error) End Try End Sub


Sie können erkennen das wir die entsprechenden Schlüssel selbst erstellen und wieder löschen. Dieses Verfahren bezeichnet man daher auch als Selbstregistrierung. Sie können auch erkennen das wir einen Codebase Eintrag vornehmen. Dieser ist immer dann nötig wenn Ihr Assembly nicht im GAC installiert wird, andernfalls können Sie auf den Codebase Eintrag verzichten. Fazit: Was Sie bei der manuellen Weitergabe auf andere Systeme im wesentlichen tun müssen ist das Tool Regasm.exe aufzurufen und ihren Register/Unregister Methoden entprechend vorzubereiten. In der folgenden Übersicht sehen Sie eine kurze Tabelle für die typischen Einträge eines Automation Addins:

HKEY_CURRENT_USER\Software\Microsoft\Office\<Ihrer_Office_Anwendung>\Addins\<ProgID_Ihrer Addin_Klasse>

DWORD LoadBehavior Definiert das Ladeverhalten des Addins
REG_SZ FriendlyName Der angezeigte Name des Addins
REG_SZ Description Eine zustätzliche Kurzbeschreibung des Addins


MSDN Library: Registrierungseinträge für Add-Ins auf Anwendungsebene



Weitergabe als Installationspaket(.msi)

Für die Weitergabe als .MSI Paket empfiehlt sich in Visual Studio ein Setup Projekt zu erstellen. Klicken Sie dazu auf die Schaltfläche Neues Projekt hinzufügen innerhalb Ihrer Solution. Im nächsten Schritt müssen Sie die Projektausgabe Ihres AutomationAddin Projekts dem Setup Projekt hinzufügen. Klicken Sie dazu auf die Schaltfläche Hinuzfügen/Projektausgabe und wählen Ihr AutomationAddin Projekt. Die notwendige Registrierung die wie oben erklärt durch Regasm.exe vorgenommen entfällt hier da der Windows-Installer sich darum kümmert. Hierzu müssen Sie die Registereigenschaft für die zu installierende Projektausgabe auf den Wert vsdrpCOM setzen. Dieses Verfahren hat leider den Nachteil das der Windows Installer nicht die oben beschrieben Register Funktionen aufruft. Sie müssen die Registrierungsschlüssel für Ihre Office Anwendungung in Ihrem Setup Projekt extra definieren damit das Addin während der Installation eingetragen wird. Wie dies geht sehen Sie weiter unten.

Sie müssen ausserdem dafür sorgen der Codebase Eintrag vorgenommen wird, andernfalls muss das Assembly im GAC installiert werden. Wichtig: Für eine Registrierung im GAC benötigt Ihr Assembly einen starken Namen. Zuerst müssen Sie den GAC Ordner innerhalb ihres Setups definieren. Wechseln Sie dazu in der Ansicht ins Dateisystem. Klicken Sie auf die Schaltfläche Speziellen Ordner hinzufügen und wählen Sie Cacheordner für globale Assembly. Wechseln Sie nun die Eigenschaften der Projektausgabe und setzen Sie den Wert Folder auf den eben hinzugefügten Ordner Cacheordner für globale Assembly. Um die erforderlichen Registrierungswerte für Office zu erstellen wechseln Sie in der Ansicht zu Registrierung und definieren die Schlüssel HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeAnwendung\Addins\IhrAddin mit den erforderlichen Werten.

Exemplarisches Vorgehen für das erstellen eines vollständigen Setup Projekts

In der folgenden Veranschaulichung wird ein vollständiges Setup Projekt für ein Automation AddIn erstellt das im GAC registriert wird und von Microsoft Excel geladen werden soll.

Download Beispielprojekt

Schritt 1: Hinzufügen des Setup Projekts zum Addin Projekt

Deploy1_DE_VB 


Schritt 2: Hinzufügen der Projektausgabe des Addin Projekts zum Setup Projekt

Deploy2_DE_VB Deploy3_DE_VB 
 


Schritt 3: Bekanntmachen des GAC Ordners

Deploy4_DE_VB  
Deploy5_DE_VB 


Schritt 4: GAC Ordner als Installationsziel für ihr Addin angeben

Deploy6_DE_VB 



Schritt 5: Registrierung für COM festlegen

Deploy7_DE_VB  


Schritt 6: Registrierungsschlüssel definieren

Deploy8_DE_VB  
Deploy9_DE_VB  



Schritt 7: Projekt erstellen

Deploy10_DE_VB  


Schritt 8: Das Setup Projekt stellt fest das die generierte Typenbibliothek(COM) im GAC nicht installierbar ist. Die Typenbibliothek wird von der Installation ausgeschlossen da sie zur Laufzeit nicht benötigt wird.

Deploy11_DE_VB
Deploy12_DE_VB

 
Klicken Sie erneut auf die Schaltfläche “Erstellen” um erfolgreich ein Setup Projekt für Ihre Anwendung zu erstellen. Im Ausgabeverzeichniss werden Sie eine .msi Datei und eine .exe Datei vorfinden. Die .exe Datei hat die Aufgabe zu prüfen ob die richtige Windows Installer Runtime auf dem Zielsystem installiert ist. Wenn dies der Fall ist wird die .exe Datei die .msi Datei zur Ausführung bringen, andernfalls den Download und die Installation der korrekten Windows Installer Runtime anbieten und danach Ihr Installationspaket(.msi Datei) zur Ausführung bringen.

Download Beispielprojekt

Last edited May 13, 2012 at 4:09 PM by SebastianDotNet, version 16

Comments

No comments yet.