Information about designing Office add-ins by using the .NET Framework

Microsoft Office XP and later versions of Microsoft Office have several types of add-ins that you can create by using Microsoft Visual Studio .NET. You can create the following types of add-ins:

• Office COM add-ins
• Microsoft Excel Automation add-ins
• Excel RTD Servers
• Microsoft Word WLLs
• Excel XLLs

This article contains information about using the .NET development platform for building the previous types of Office add-ins.

COM-based add-ins

COM add-ins, Automation add-ins, and RTD Servers are types of Office add-ins that are designed around the Component Object Model (COM). COM Interop services are provided by the common language runtime to permit managed code that runs in the .NET environment to communicate with COM servers by using a wrapper between your managed code and the COM server. This wrapper is known as an Interop Assembly (IA).

While any number of IAs may exist that describe a particular COM type, only one IA is considered the Primary Interop Assembly (PIA). The PIA contains the official description of the types as defined by the publisher of those types and may also contain certain customizations that make the types easier to use from the managed code. Any IA that is not provided by the publisher of the COM types is considered unofficial and must be avoided. Microsoft provides PIAs for Office XP and for later versions of Office. When you develop a managed code COM-based add-in for Office, you must use the PIA that is provided by Microsoft that matches the version of the target Office application.

The Office XP PIAs are designed against the .NET Framework 1.0. The Office XP PIAs are available for download and may be redistributed with your .NET solutions:

For more information, click the following article number to view the article in the Microsoft Knowledge Base: Office 2003 and later versions of Office include PIAs with the Office Setup program. The Office PIAs may be installed with the Office Setup program provided that your computer has the .NET Framework 1.1 or a later version of the .NET Framework already installed. You can distribute the Office PIAs by using the Microsoft Office Primary Interop Assemblies (PIAs) redistributable.

For more information, click the following article number to view the article in the Microsoft Knowledge Base: When you develop a managed code Office add-in, you must know the following information:

• Multiple versions of Office
  
  Microsoft does not guarantee that the Office PIAs will be backwardly compatible or that the various versions of the Office PIAs can be run side-by-side in the same instance of an Office application. Office XP managed code add-ins must be built against the Office XP PIAs. The Office 2003 managed code add-ins must be built against the Office 2003 PIAs. The Office 2007 managed code add-ins must be built against the Office 2007 PIAs. Therefore, if you build an add-in solution that you intend to use with several versions of Office, Microsoft recommends that you build a version of your add-in for each version of Office that you intend to support.
• Security
  
  Because managed code is not native, the COM registry entries that are made for an Office component that you build with .NET point to the .NET runtime engine (Mscoree.dll) and not to your assembly. Because Mscoree.dll is not digitally signed, and Office determines whether an add-in is safe based on a digital signature, your users may receive a macro-warning dialog box that prompts them to enable your add-in or to disable your add-in. This behavior occurs even if you digitally signed your assembly. To avoid this macro-warning dialog box, you can use a custom "shim" for your component.
  
  For more information about deployment of managed COM add-ins in Office XP, visit the following Microsoft Developer Network (MSDN) Web site:
  http://msdn2.microsoft.com/en-us/library/aa164016(office.10).aspx (http://msdn2.microsoft.com/en-us/library/aa164016(office.10).aspx)
  For more information about using the COM add-in shim solution to deploy managed COM add-ins in Office XP, visit the following MSDN Web site:
  http://msdn2.microsoft.com/en-us/library/aa140200(office.10).aspx (http://msdn2.microsoft.com/en-us/library/aa140200(office.10).aspx)
  For more information about using the COM add-in shim to trust Outlook 2002 add-ins that are built by using Visual Studio .NET, visit the following MSDN Web site:
  http://msdn2.microsoft.com/en-us/library/aa140152(office.10).aspx (http://msdn2.microsoft.com/en-us/library/aa140152(office.10).aspx)
  For more information about using the smart tag shim solution to deploy managed smart tags in Office XP, visit the following MSDN Web site:
  http://msdn2.microsoft.com/en-us/library/aa163615(office.10).aspx (http://msdn2.microsoft.com/en-us/library/aa163615(office.10).aspx)
• Isolation
  
  When you use a shim, your managed COM add-in is loaded in a separate AppDomain. This is an advantage and is particularly important in scenarios where there may be multiple managed COM add-ins in the same Office process. When your add-in is in its own AppDomain, your add-in may use whatever version of a dependent assembly that your add-in requires. Also, your add-in will be largely isolated from problems that may occur if there are other add-ins in other AppDomains.
• Setup
  
  If you create a COM add-in with Visual Studio .NET, a default Setup project is added to your solution. The default Setup project in the solution includes the PIAs that are referenced by your COM add-in. The default Setup project includes the PIAs in the Setup package. This is true even when your PIA references have the CopyLocal property set to false and a Path property that points to the PIA in the global assembly cache (GAC).
  
  You may redistribute Office XP PIAs. When you redistribute an Office XP PIA, you must install the Office XP PIA in the GAC. However, you must not deploy an Office 2003 PIA. When you build an add-in that targets Office 2003, you must exclude the Office 2003 PIAs from the Setup project. When the add-in loads in the target Office 2003 application, the add-in will correctly use the PIAs in the GAC at runtime. The add-in will correctly fail if the PIAs are not found in the GAC. The add-in will not fall back to load any other version of the PIA.

Word WLLs and Excel XLLs

Word WLLs and Excel XLLs are standard Windows DLLs that implement and export specific methods to extend Word functionality and Excel functionality. Word WLLs and Excel XLLs are based on older CAPI technologies. There have been no enhancements and no documentation updates to Word WLLs and Excel XLLs since Microsoft Office 97. Microsoft has not tested managed code with these older technologies. Therefore, Microsoft does not recommend using managed code with a WLL solution or with an XLL solution.

Managed code solution types that were introduced in Office 2003

Office 2003 introduced several new technologies that target the .NET development environment, as follows:

For more information about Visual Studio Tools for Office managed code extensions for Excel and Word, visit the following MSDN Web site:For more information about managed smart tags, visit the following Microsoft Web site:For more information about managed smart documents, visit the following Microsoft Web site: Microsoft Office Professional Edition 2003, Microsoft Office Word 2003, and Microsoft Office Excel 2003 include a loader that is designed specifically to load managed-code extensions, managed smart tag solutions, and managed smart document solutions.

For more information, click the following article numbers to view the articles in the Microsoft Knowledge Base: For more information about Microsoft Office development with Visual Studio, visit the following MSDN Web site: