Location>code7788 >text

C# Office COM Add-in

Popularity：889 ℃/2025-03-31 20:08:09

Office COM Add-in Development Notes

1. Implement interface IDTExtensibility2

This is the most basic interface to implement Office COM add-on

Just add COM, reference Microsoft, Add-In, Designer

The corresponding file only contains the enumerations used in the IDTExtensibility2 interface, ext_ConnectMode, ext_DisconnectMode,
You can reduce the module reference and copy the code into your own project by yourself. Note that IDTExtensibility2 cannot be confused.

⚠ Note: When developing Office or WPS COM add-ons to add COM references, you need to install the corresponding suite to find the relevant COM components. When adding WPS COM references, you will be affected by the order of installations and administrator rights of the two, resulting in the inability to add references. If VS errors cannot be added, you need to uninstall Office to be added successfully. But the following will mention that only one of the COM components needs to be compatible with Office and WPS at the same time

#if BrandName1
 namespace BrandName1 // Brand 1
 #else
 namespace BrandName2 // Brand 2
 #endif
 {
     [Obfuscation] // Not to be obfuscated
     [ComVisible(true)] // The COM component class is visible, and the type should be set to public
     [Guid("XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")] // CLSID
     // [ProgId("")] // The ProgID of the Office COM add-in must be the same as the full name of the class
     public class OfficeAddIn: IDTExtensibility2
     {
         public void OnConnection(
             object application, ext_ConnectMode connectMode,
             object addInInst, ref Array custom)
         {
             ("OnConnection"); // Add-in that has been successfully registered will pop up when the corresponding application is started
         }

         // Other IDTExtensibility2 interface methods...
     }
 }

⚠ Note: Office COM add-ons must be of classProgIDCompletely matches the full name of the class. When the ProgID feature is not set, the full name of the class is used by default, so there is no need to set it; and the class cannot be confused, and the interface it inherits cannot be confused.

ProgID is related to the product and corresponding functions, and file associations will also be used. The recommended name is., so in the example, BrandName1 is the namespace and OfficeAddIn is the class name, so ProgID is. To distinguish brands, different namespaces are used instead of different class names in brand conditional compilation, which is more in line with the specifications and is better to write registered code.

2. Register Office COM add-on

The registry of COM CLSID and Office products have HKCU, HKLM and 64 and 32-bit entries. In order to improve compatibility, registration information can be added under these registry entries.

Register COM Components

C# Registration COM Components are generally registered by calling files, distinguishing between digits and runtime versions.

%windir%\\Framework[64]_"ver"_\  /codebase [/u]

The function is to add registry keys to avoid the system missing the file. In order to add log output, you can write the registry to implement it yourself.

{HKCU|HKLM}\Software\Classes
    ProgID
        ● "" = 'ProgID'
        CLSID
            ● "" = 'CLSID'
    [Wow6432Node\]CLSID\'CLSID'
        ● "" = 'ProgID'
        Implemented Categories\{62C8FE65-4EBB-45e7-B440-6E39B2CDBF29}
        InprocServer32
            ● "" = ""
            ● "Assembly" = ''
            ● "Class" = 'ProgID'
            ● "CodeBase" = ''
            ● "RuntimeVersion" = '' 
            ● "ThreadingModel" = "Both"
        ProgId
            ● "" = 'ProgID'

⚠ Note: The registration method will use reflection. If the referenced assembly file is not placed in the same directory and the system does not register the interface inherited by the COM class, an error will occur, resulting in the registration failure. If the registration method is the same as   , the type itself will be used. In order to avoid the user not installing COM component-related applications, the referenced assembly needs to be packaged.

⚠ Note: When creating assembly of different brands of assembly and registering for the same COM component project, if the file names of the two assembly are the same, the signatures and versions are the same, the full names of the two assembly will be the same, resulting in the system being indistinguishable. The way to distinguish is that there is at least one difference between the three. The easiest way is to conditionally compile and set different version numbers.

⚠ Note: To improve compatibility, the target platform selects AnyCPU to be compatible with 64/32-bit systems and software. When running as a COM component, it is run as an assembly referenced by the .NET virtual machine process. Just set the target framework to .NET Framework 3.5, and you do not need a file to be compatible with 3.5 and 4.0, without compiling multiple framework versions. Supports .dll and .exe files, as long as it is a .NET assembly. If you can register it as a COM component exe, it is still necessary to register it.

Add to Office Add-in List

You need to create a new add-in class ProgID subkey with the same name under the add-in list, and add three necessary registry key values.

{HKCU|HKLM}\Software\[Wow6432Node\]Microsoft\Office
     <app>
         AddIns
             'ProgID'
                 ● FriendlyName = "Friendly Name Shown in Add-in List"
                 ● Description = "Description displayed in the add-in list"
                 ● LoadBehavior = 3 (connect and load on startup)

In addition, you can also add CommandLineSafe = 1, indicating that the command line operation is safe, which may reduce pop-up warnings

After registering the sample plug-in through these two steps, when the corresponding Office application is started, a message box will pop up, verifying that the registration is successful.

3. Implement interface IRibbonExtensibility

This interface is used to add a custom UI in Ribbon of Office application

Add COM Reference Microsoft OfficeObject Library ,Yes Office version number

To improve compatibility, you can install Office 2007 to obtain the COM version 12.0, copy the corresponding files to the project directory, and modify the reference to relative files to avoid the inability to generate on other computers without Office 2007 installed. Note that this interface must also be inherited by the add-in class, so it cannot be confused.

There is only one interfaceGetCutsomUIThe method requires returning a string in XML format

For code readability, it is recommended to write and load XML resource files using the method of

And after adding namespace in VS, there will be a list of candidate words when writing element attributes, which is very convenient

<?xml version="1.0" encoding="utf-8"?>
<customUI xmlns="/office/2006/01/customui">
  <ribbon>
    <tabs>
      <tab  getLabel="GetLabel">
        <group  getLabel="GetLabel">
          <button  size="large"
            onAction="OnButtonPressed"
            getLabel="GetLabel"
            getImage="GetImage"/>
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

public class OfficeAddIn: IDTExtensibility2, IRibbonExtensibility
 {
     public string GetLabel(IRibbonControl control)
     {
         switch()
         {
             case "TestTab": return "Test Tab";
             case "TestGroup": return "Test Group";
             case "TestButton": return "Test Button";
         }
         return null;
     }

     public {Bitmap|IPictureDisp} GetImage(IRibbonControl control)
     {
         // Return the control image, supports Bitmap or IPictureDisp type return value
     }

     public void OnButtonPressed(IRibbonControl control)
     {
         ("Test Button Clicked!");
     }
 }

CustomUI Notes

It is recommended to carry XML declaration part specificationutf-8Encoding, otherwise if there is Chinese, it will be garbled.

customUINamespace in element, year and month can be used2009/07or2006/01, but Office 2007 does not support parsing the former

The corresponding attributes can be used for the text, images, floating prompts, etc. of the control.label、imageSet it directly in XML. You can also use the corresponding callback methodgetLabel、getImage. The method of using callback methods requires declaring the same name public method in the add-in class, such as writing in XMLgetLabel="GetLabel", the corresponding one must be written in C#public string GetLabel (IRibbonControl control)Method, similar to the event binding of WPF XAML, supports multiple controls to use the same method and return appropriate values ​​according to the control's id

In Article 3, attributes and callback methods are mutually exclusive, and only one of them is allowed. In addition, the image can also be usedBuilt-in image propertiesimageMso,andimageandgetImageIt is also mutually exclusive, such asimageMso="FileSaveAs"Use built-in Save As Image

If useddynamicMenucontrol, itsgetContentThe method also needs to return an XML format string, but unlike Article 1, there cannot be an XML declaration part, otherwise the parsing will fail.

Case sensitive, case errors will cause parsing to fail

Using transparent background images

CustomUI controlgetImageMethod supports direct returnBitmapType, Office supports transparent backgroundBitmap, but WPS does not support it and will be filled with a light gray background. Here you can convert and returnIPictureDisptype

It is also worth mentioning that after Office switches to dark themes, black and gray monochrome images will be automatically converted to white images. WPS does not have this mechanism

IPictureDisp is defined in COM component OLE Automation, generally adding Microsoft OfficeObject Library Reference will be automatically added. The corresponding file is  . We only need to use the IPictureDisp interface, which can also reduce the module reference and copy the code into our own project.

[DllImport("", ExactSpelling = true, PreserveSig = false)]
 static extern IPictureDisp OleCreatePictureIndirect(
     ref PictDesc pictdesc,
     [MarshalAs()] Guid iid,
     [MarshalAs()] bool fOwn);

 struct PictDesc
 {
     public int cbSizeofstruct;
     public int picType;
     public IntPtr hbitmap;
     public IntPtr hpal;
     public int unused;
 }

 public static IPictureDisp CreatePictureIndirect(Bitmap bitmap)
 {
     var picture = new PictDesc
     {
         cbSizeofstruct = (typeof(PictDesc)),
         picType = 1,
         hbitmap = (), // Create a pure transparent background bitmap
         hpal = ,
         unused = 0,
     };
     return OleCreatePictureIndirect(ref picture, typeof(IPictureDisp).GUID, true);
 }

Are there ginseng and ginsengColorTwo overloads, no parameter overloads are passed internallyCall another overload, which should be returned directlyBitmapThere will be light gray fill-related in WPS.
It should be noted thatGetHbitmapThe Alpha value of the color will not be used inside the method. Create a pure transparent background image handle and should be used. 255,0,0,0Instead``0,255,255,255

CustomUI refresh control

  1. usecustomUIElementalonloadCallback method, recorded in C#IRibbonUIObject, call itInvalidateMethod refreshes the entire UI, or callsInvalidateControl(string id)Refresh the specified control according to id
public class OfficeAddIn : IDTExtensibility2, IRibbonExtensibility
{
    IRibbonUI ribbon;

    public void OnCustomUILoad(IRibbonUI ribbon)
    {
         = ribbon;
    }
    
    internal void Invalidate()
    {
        ribbon?.Invalidate();
    }
    
    internal void InvalidateControl(string id)
    {
        ribbon?.InvalidateControl(id);
    }
}
  1. dynamicMenuControlsinvalidateContentOnDrop="true"Can be retriggered every time it expandsgetContentRefresh content

4. Office interoperability capabilities

You need to add an interoperability library that references the corresponding Office application, which can easily jump to MSDN documents in VS

Add COM Reference Microsoft Object Library

The following demonstration of Office exporting PDF capabilities is only for demonstration, and it also requires the release of COM objects.

The ExportAsFixedFormat method has many optional parameters, which supports setting the number of pages printed, including document information, generating bookmarks, etc.

⚠ Note: Exporting PDF/XPS at Office 2007 (only 32-bit version) will prompt that when this function is not installed, you need to use the EXP_PDF.dll and EXP_XPS.dll files that are only available in Office 2010, and copy them to the shared directory of Office 2007.

%CommonProgramFiles[(x86)]%\Microsoft Shared\OFFICE12

Word export PDF

using ;

public class OfficeAddIn : IDTExtensibility2, IRibbonExtensibility
{
    Application app;

    public void OnConnection(
        object application, ext_ConnectMode connectMode, 
        object addInInst, ref Array custom)
    {
        if (application is Application)
            app = (Application)Application;
    }

    public void OnButtonPressed(IRibbonControl control)
    {
        app?.ActiveDocument?.ExportAsFixedFormat(fileName, );
    }
}

Excel export PDF

using;
 // Workbook
 app?.ActiveWorkbook?.ExportAsFixedFormat(, fileName);

 // Worksheet
 (app?.ActiveSheet as Worksheet)?.ExportAsFixedFormat(, fileName);

 // Chart, WPS does not support
 ?.ExportAsFixedFormat(, fileName);

 // Select the area in the box
 var range = as Range;
 var sheet = ;
 var area = ;
  = ; // Set the print area to the selected area
 (, fileName);
  = area; // Restore the printing area

PowerPoint Export PDF

using ;

app?.ActivePresentation?.ExportAsFixedFormat(fileName, );

Publisher Export PDF

using ;

app?.ActiveDocument?.ExportAsFixedFormat(, fileName);

Outlook exports emails as PDF

using;
 using;

 var mailItem = outlook?.ActiveExplorer()?.Selection?.OfType<MailItem>()?.FirstOrDefault();
 var inspector = mailItem?.GetInspector;
 var document = inspector?.WordEditor as Document;
 document?.ExportAsFixedFormat(fileName, );
 // GetInspector will open a hidden window, which consumes more memory and needs to be closed in time
 inspector?.Close();

5. Implement WPS COM add-on

You must add to the WPS add-in list based on the Office COM add-in (including adding to the Office add-in list)

Add to WPS Add-in List

Word corresponds to WPS, Excel corresponds to ET, PowerPoint corresponds to WPP, and does not distinguish between 64/32 bits

HKCU\Software\kingsoft\office
    {WPS|ET|WPP}
        AddinsWL
            'ProgID' = ""

Office and WPS COM components correspondence table

⚠ Note: In order to be compatible with each other, the COM interfaces related to Office, Word, Excel, and PowerPoint use the same CLSID. If the plug-in needs to be compatible with both, the corresponding interoperable library files only need one set. Due to the different namespaces in the assembly, and the user will basically only install one set. The interoperable library files must be copied to the running directory, otherwise it will not be compatible at the same time.

#### Office #### WPS
Microsoft Add-In Designer
 Kingsoft Add-In Designer
Microsoft Office  Object Library
 		Upgrage WPS Office  Object Library
Microsoft Word  Object Library
 		Upgrade Kingsoft WPS  Object Library
Microsoft Excel  Object Library
 		Upgrage WPS Spreadsheets  Object Library
Microsoft PowerPoint  Object Library
 		Upgrage WPS Presentation  Object Library

6. Uninstall and clean the registry

In addition to cleaning up the registry of COM components and add-ons added above, you can also clean up the following related registries:

  1. HKCU\Software\Microsoft\Office\<app>\AddinsDataPlugin data

  2. HKCU\Software\Microsoft\Office\<ver>\Common\CustomUIValidationCacheCustomUI Verification Cache

  3. HKCU\Software\Microsoft\Office\<ver>\<app>\AddinsVersion plugin list

  4. HKCU\Software\Microsoft\Office\<ver>\<app>\AddInLoadTimesVersion loading times

  5. HKCU\Software\Microsoft\Office\<ver>\<app>\Resiliency\NotificationReminderAddinDataOffice Disable Notifications

7. Other issues

Not loaded, there is a running error when loading COM add-in

This is a headache, and there may be many reasons, but Office has no error logs, making it difficult to troubleshoot problems

Microsoft Official BlogSome answers were given, and some situations have been reappeared:

  • Deployment issue: COM component registry content is missing or key value. Pay attention to the number of bits in the COM component and Office add-in registry

  • Running problem: It is more obvious in Outlook. It starts slowly and stutters. Do not call the Sleep function at startup. At the mildest, Office directly prompts you to disable the plug-in, and at the worst, there is a problem that is not loaded.

Outlook operation before exit

Outlook 16.0 (other versions not tested) will not fire when exitingOnBeginShutdown``OnDisconnection, the reason is unknown, it should be an Outlook own bug, so the Outlook plug-in should not perform pre-exit operations in these two methods

After testing, the program will be fired when it exits., but it won't trigger (it's too late?), the former can be used to perform pre-exit operations, such as saving configuration and releasing resources

The process does not end after the Office application is closed

This problem usually occurs because the COM object resources are not released cleanly, but it is difficult to ensure that all COM objects are released in a timely and correctly in a frequent manner using Office interoperability. In order to get the process to exit correctly, it is not availableIf you like the forced method, you can manually end the process. First, force ending the process may cause the document to be saved abnormally when you open the document next time. Second, the plug-in can be manually uninstalled during the program operation. You can use the method of uninstalling the current application domain to solve the problem friendly.

public void OnDisconnection(ext_DisconnectMode removeMode, ref Array custom)
{
    try
    {
        ();
    }
    catch (CannotUnloadAppDomainException)
    {
        // ignored
    }
}

Related information

How to Generate Office COM Add-in with Visual C# .NET - Office

[MS-CUSTOMUI]: CustomUI | Microsoft Learning

Troubleshooting COM Add-In Loading Failure | Microsoft Learning

<Previous Next>