Een Office COM-invoegtoepassing bouwen met behulp van Visual C# .NET

Artikel
06/20/2023
Van toepassing op:

Microsoft Office XP, Microsoft Office 2003, Microsoft Office 2007

Samenvatting

Microsoft Office XP, Microsoft Office 2003 en Microsoft Office 2007 ondersteunen een uniforme ontwerparchitectuur voor het bouwen van invoegtoepassingen voor toepassingen om Office-toepassingen te verbeteren en te beheren. Deze invoegtoepassingen worden COM-invoegtoepassingen (Microsoft Component Object Model) genoemd. In dit stapsgewijze artikel worden Office COM-invoegtoepassingen besproken en wordt beschreven hoe u een Office COM-invoegtoepassing maakt met behulp van Microsoft Visual C# .NET.

De INTERFACE IDTExensibility2

Een COM-invoegtoepassing is een IN-process COM-server of ActiveX Dynamic Link Library (DLL) waarmee de INTERFACE IDTExensibility2 wordt geïmplementeerd, zoals beschreven in de Microsoft Add-in Designer-typebibliotheek (Msaddndr.dll). Alle COM-invoegtoepassingen nemen over van deze interface en moeten elk van de vijf methoden implementeren.

OnConnection

De gebeurtenis OnConnection wordt geactiveerd wanneer de COM-invoegtoepassing is verbonden. De invoegtoepassing kan worden verbonden bij het opstarten, door de eindgebruiker of via Automation. Als de gebeurtenis OnConnection wordt geretourneerd, wordt gezegd dat de invoegtoepassing is geladen. Als er een foutbericht wordt geretourneerd, geeft de hosttoepassing onmiddellijk de verwijzing naar de invoegtoepassing vrij en wordt het object vernietigd.

De gebeurtenis OnConnection heeft de volgende vier parameters:

Toepassing: Een verwijzing naar het hosttoepassingsobject.
ConnectMode: een constante die aangeeft hoe de invoegtoepassing is verbonden. De invoegtoepassing kan op de volgende manieren worden verbonden:
- ext_cm_AfterStartup: De invoegtoepassing wordt gestart door de eindgebruiker vanuit het dialoogvenster COM-invoegtoepassingen.
- ext_cm_CommandLine: De invoegtoepassing is verbonden vanaf de opdrachtregel. Houd er rekening mee dat dit niet van toepassing is op het bouwen van COM-invoegtoepassingen voor Office-toepassingen.
- ext_cm_External: De invoegtoepassing wordt via Automation verbonden door een externe toepassing. Houd er rekening mee dat dit niet van toepassing is op het bouwen van COM-invoegtoepassingen voor Office-toepassingen.
- ext_cm_Startup: De invoegtoepassing wordt gestart door de host bij het opstarten van de toepassing. Dit gedrag wordt bepaald door een instelling in het register.
AddInInst: Een verwijzing naar het COMAddIn-object dat verwijst naar deze invoegtoepassing in de COMAddIns-verzameling voor de hosttoepassing.
Aangepast: een matrix met waarden van het type Variant die door de gebruiker gedefinieerde gegevens kunnen bevatten.

OnDisconnection

De OnDisconnection-gebeurtenis wordt geactiveerd wanneer de COM-invoegtoepassing is losgekoppeld en vlak voordat deze uit het geheugen wordt verwijderd. De invoegtoepassing moet in dit geval resources opschonen en eventuele wijzigingen in de hosttoepassing herstellen.

De gebeurtenis OnDisconnection heeft de volgende twee parameters:

RemoveMode: een constante die aangeeft hoe de verbinding met de invoegtoepassing is verbroken. De verbinding met de invoegtoepassing kan op de volgende manieren worden verbroken:
- ext_dm_HostShutdown: De verbinding met de invoegtoepassing wordt verbroken wanneer de hosttoepassing wordt gesloten.
- ext_dm_UserClosed: de verbinding met de invoegtoepassing wordt verbroken door de eindgebruiker of een Automation-controller.
Aangepast: een matrix met waarden van het type Variant die door de gebruiker gedefinieerde gegevens kunnen bevatten.

OnAddInsUpdate

De gebeurtenis OnAddInsUpdate wordt geactiveerd wanneer de set geregistreerde COM-invoegtoepassingen wordt gewijzigd. Met andere woorden, wanneer een COM-invoegtoepassing wordt geïnstalleerd of verwijderd uit de hosttoepassing, wordt deze gebeurtenis geactiveerd.

OnStartupComplete en OnBeginShutdown

Zowel de methode OnStartupComplete als de OnBeginShutdown-methode worden aangeroepen wanneer de hosttoepassing is vertrokken of een status invoert waarin gebruikersinteractie moet worden vermeden omdat de toepassing bezig is met het laden of lossen van zichzelf uit het geheugen. De methode OnStartupComplete wordt alleen aangeroepen als de invoegtoepassing is verbonden tijdens het opstarten en de methode OnBeginShutdown wordt alleen aangeroepen als de host de verbinding met de invoegtoepassing tijdens het afsluiten verbreekt.

Omdat de gebruikersinterface voor de hosttoepassing volledig actief is wanneer deze gebeurtenissen worden geactiveerd, zijn ze mogelijk de enige manier om bepaalde acties uit te voeren die anders niet beschikbaar zouden zijn voor de gebeurtenis OnConnection en de OnDisconnection-gebeurtenis.

REGISTRATIE VAN COM-invoegtoepassing

Naast de normale COM-registratie moet een COM-invoegtoepassing zich registreren bij elke Office-toepassing waarin deze wordt uitgevoerd. Als u zichzelf wilt registreren bij een bepaalde toepassing, moet de invoegtoepassing een subsleutel maken met behulp van de ProgID als de naam voor de sleutel, op de volgende locatie:

HKEY_CURRENT_USER\Software\Microsoft\Office\OfficeApp\Addins\ProgID

De invoegtoepassing kan waarden op deze sleutellocatie opgeven voor zowel een beschrijvende weergavenaam als een volledige beschrijving. Daarnaast moet de invoegtoepassing het gewenste laadgedrag opgeven met behulp van een DWORD-waarde met de naam LoadBehavior. Deze waarde bepaalt hoe de invoegtoepassing wordt geladen door de hosttoepassing en bestaat uit een combinatie van de volgende waarden:

0 = Verbinding verbreken - Is niet geladen.
1 = Verbonden - Is geladen.
2 = Bootload - Laden bij het opstarten van de toepassing.
8 = DemandLoad - Alleen laden wanneer de gebruiker hierom vraagt.
16 = ConnectFirstTime - Laad slechts één keer (bij de volgende keer opstarten).

De opgegeven standaardwaarde is 0x03 (verbonden | Bootload).

Invoegtoepassingen die IDTExtensibility2 implementeren, moeten ook een DWORD-waarde met de naam CommandLineSafe opgeven om aan te geven of de invoegtoepassingen veilig zijn voor bewerkingen die geen ondersteuning bieden voor een gebruikersinterface. Een waarde van 0x00 geeft Onwaar aan en een waarde van 0x01 geeft Waar aan.

Een COM-invoegtoepassing bouwen met behulp van Visual C# .NET

Zoals eerder vermeld, is een Office COM-invoegtoepassing een com-server in proces die wordt geactiveerd door een Office-toepassing via de COM-runtimelaag. Daarom vereist het ontwikkelen van een COM-invoegtoepassing in .NET dat het invoegtoepassingsonderdeel wordt geïmplementeerd in .NET en vervolgens via de COM-interoperabiliteitslaag beschikbaar moet worden gemaakt voor de COM-clients (dat wil gezegd hebben van de Office-toepassingen).

Voer de volgende stappen uit om een COM-invoegtoepassing te maken in Visual C# .NET:

Maak in Visual C# .NET een klassebibliotheekproject.
Voeg een verwijzing toe naar de typebibliotheek waarmee IDTExtensibility2 wordt geïmplementeerd. De primaire interoperabiliteitsassembly hiervoor is al beschikbaar onder de naam Uitbreidbaarheid.
Voeg een verwijzing toe naar de Microsoft Office-objectbibliotheek. De primaire assembly voor interoperabiliteit hiervoor is al beschikbaar onder de naam Office.
Maak een openbare klasse in de klassebibliotheek waarmee IDTExtensibility2 wordt geïmplementeerd.
Nadat de klassenbibliotheek is gebouwd, registreert u de bibliotheek voor COM-interoperabiliteit. Hiervoor genereert u een sterke assembly met de naam voor deze klassebibliotheek en registreert u deze vervolgens met COM-interoperabiliteit. U kunt Regasm.exe gebruiken om een .NET-onderdeel te registreren voor COM-interop.
Maak registervermeldingen zodat Office-toepassingen de invoegtoepassing kunnen herkennen en laden.

U kunt ervoor kiezen om al deze stappen uit te voeren of u kunt een .NET-project van het type Gedeelde invoegtoepassing maken. Hiermee start u de wizard Uitbreidbaarheid, waarmee u een COM-invoegtoepassing kunt maken in .NET.

De wizard Uitbreidbaarheid maakt een Visual C# .NET-klassebibliotheekproject samen met een Connect-klasse waarmee de IDTExtensibility2-interface wordt geïmplementeerd. De basiscode waarmee de lege leden van IDTExtensibility worden geïmplementeerd, wordt ook gegenereerd. Dit project bevat verwijzingen naar uitbreidbaarheid en Office-assembly's. Voor de build-instellingen van het project is Registreren voor COM Interop geselecteerd. Het bestand assemblysleutel (.snk) wordt gegenereerd en wordt vermeld in het kenmerk AssemblyKeyfile in Assemblyinfo.vb.

Samen met het klassebibliotheekproject genereert de wizard een installatieproject dat u kunt gebruiken om de COM-invoegtoepassing op andere computers te implementeren. U kunt dit project desgewenst verwijderen.

Stapsgewijze voorbeeld

Klik in het menu Bestand in Microsoft Visual Studio .NET op Nieuw en klik vervolgens op Project.
Vouw in het dialoogvenster Nieuw project andere projecten uit onder Projecttypen, selecteer Uitbreidbaarheidsprojecten en selecteer vervolgens de sjabloon Gedeelde invoegtoepassing.
Typ MyCOMAddin als de naam van de invoegtoepassing en klik op OK.
Wanneer de wizard Uitbreidbaarheid wordt weergegeven, voert u de volgende stappen uit:
1. Selecteer op pagina 1 Een invoegtoepassing maken met Visual C# en klik vervolgens op Volgende.
2. Selecteer op pagina 2 de volgende hosttoepassingen en klik vervolgens op Volgende:
  - Microsoft Word
  - Microsoft PowerPoint
  - Microsoft Outlook
  - Microsoft Excel
  - Microsoft Access
3. Geef op pagina 3 een naam en beschrijving op voor de invoegtoepassing en klik vervolgens op Volgende.
  
  Opmerking De naam en beschrijving van de invoegtoepassing worden weergegeven in het dialoogvenster COM-invoegtoepassing in de Office-toepassing.
4. Selecteer op pagina 4 alle beschikbare opties en klik vervolgens op Volgende.
5. Klik op Voltooien.
Klik in het menu Project op Verwijzing toevoegen. Klik op System.Windows.Forms.DLL in de lijst met onderdelen, klik op Selecteren en klik vervolgens op OK.
Voeg het volgende toe aan de lijst met naamruimten in de klasse Connect:
```
using System.Reflection;
```
Voeg het volgende lid toe aan de klasse Connect:
```
private CommandBarButton MyButton;
```

Implementeer de code voor de leden van IDTExtensibility2 als volgt in de klasse Connect:

public void OnConnection(object application, Extensibility.ext_ConnectMode connectMode, object addInInst, ref System.Array custom) {
   applicationObject = application;
   addInInstance = addInInst;

if(connectMode != Extensibility.ext_ConnectMode.ext_cm_Startup)
   {
      OnStartupComplete(ref custom);
   }

}

public void OnDisconnection(Extensibility.ext_DisconnectMode disconnectMode, ref System.Array custom) {
   if(disconnectMode != Extensibility.ext_DisconnectMode.ext_dm_HostShutdown)
   {
      OnBeginShutdown(ref custom);
   }
   applicationObject = null;
}

public void OnAddInsUpdate(ref System.Array custom)
{
}

public void OnStartupComplete(ref System.Array custom)
{
   CommandBars oCommandBars;
   CommandBar oStandardBar;

try
   {
   oCommandBars = (CommandBars)applicationObject.GetType().InvokeMember("CommandBars", BindingFlags.GetProperty , null, applicationObject ,null);
   }
   catch(Exception)
   {
   // Outlook has the CommandBars collection on the Explorer object.
   object oActiveExplorer;
   oActiveExplorer= applicationObject.GetType().InvokeMember("ActiveExplorer",BindingFlags.GetProperty,null,applicationObject,null);
   oCommandBars= (CommandBars)oActiveExplorer.GetType().InvokeMember("CommandBars",BindingFlags.GetProperty,null,oActiveExplorer,null);
   }

// Set up a custom button on the "Standard" commandbar.
   try
   {
   oStandardBar = oCommandBars["Standard"];        
   }
   catch(Exception)
   {
   // Access names its main toolbar Database.
   oStandardBar = oCommandBars["Database"];      
   }

// In case the button was not deleted, use the exiting one.
   try
   {
   MyButton = (CommandBarButton)oStandardBar.Controls["My Custom Button"];
   }
   catch(Exception)
   {
      object omissing = System.Reflection.Missing.Value ;
      MyButton = (CommandBarButton) oStandardBar.Controls.Add(1, omissing , omissing , omissing , omissing);
      MyButton.Caption = "My Custom Button";
      MyButton.Style = MsoButtonStyle.msoButtonCaption;
   }

// The following items are optional, but recommended. 
   //The Tag property lets you quickly find the control 
   //and helps MSO keep track of it when more than
   //one application window is visible. The property is required
   //by some Office applications and should be provided.
   MyButton.Tag = "My Custom Button";

// The OnAction property is optional but recommended. 
   //It should be set to the ProgID of the add-in, so that if
   //the add-in is not loaded when a user presses the button,
   //MSO loads the add-in automatically and then raises
   //the Click event for the add-in to handle. 
   MyButton.OnAction = "!<MyCOMAddin.Connect>";

MyButton.Visible = true;
   MyButton.Click += new Microsoft.Office.Core._CommandBarButtonEvents_ClickEventHandler(this.MyButton_Click);

object oName = applicationObject.GetType().InvokeMember("Name",BindingFlags.GetProperty,null,applicationObject,null);

// Display a simple message to show which application you started in.
   System.Windows.Forms.MessageBox.Show("This Addin is loaded by " + oName.ToString()   , "MyCOMAddin");
   oStandardBar = null;
   oCommandBars = null;
}

public void OnBeginShutdown(ref System.Array custom)
{
   object omissing = System.Reflection.Missing.Value ;
   System.Windows.Forms.MessageBox.Show("MyCOMAddin Add-in is unloading.");
   MyButton.Delete(omissing);
   MyButton = null;
}

private void MyButton_Click(CommandBarButton cmdBarbutton,ref bool cancel) {
   System.Windows.Forms.MessageBox.Show("MyButton was Clicked","MyCOMAddin"); }

Bouw en test de COM-invoegtoepassing. Ga hiervoor als volgt te werk:
1. Klik in het menu Build op Build Solution. Houd er rekening mee dat bij het bouwen van de COM-invoegtoepassing de .NET-klasse wordt geregistreerd met de COM-interoperabiliteit.
2. Start een van de Office-toepassingen die u hebt geselecteerd als hosttoepassingen voor uw invoegtoepassing (bijvoorbeeld Microsoft Word of Microsoft Excel).
3. Nadat de invoegtoepassing is gestart, wordt de gebeurtenis OnStartupComplete van de invoegtoepassing geactiveerd en ontvangt u een bericht. Sluit het berichtvak. Houd er rekening mee dat de invoegtoepassing een nieuwe aangepaste knop met het bijschrift 'Mijn aangepaste knop' heeft toegevoegd aan de standaardwerkbalk.
4. Klik op Mijn aangepaste knop. De klikgebeurtenis voor de knop wordt verwerkt door de invoegtoepassing en u ontvangt een berichtvak. Sluit het berichtvak.
5. Sluit de Office-toepassing af.
6. Wanneer u de toepassing afsluit, wordt de gebeurtenis OnBeginShutDown geactiveerd en ontvangt u een bericht. Sluit het berichtvak om de demonstratie te beëindigen.