The release number of this article has been CHS302901
For Microsoft Visual Basic .NET versions of this article, see
.
For the Microsoft Visual Basic 6.0 version of this article, see
Move 238228.
For Microsoft Visual C 6.0, please refer to this article
230689.
This task content
•Summary
• IDTEXENSIBILITY2 interface
• OnConnection • OndisConnection • OnaddinsUpdate • OnStartupComplete and Onbeginshutdown • COM Add to register • How to use Visual C # .NET to generate a COM Add to Separation • Separation example • Reference
This page
Summary reference
summary
All Microsoft Office XP and Microsoft Office 2003 support a new unified design structure that generates an application add-in to enhance and control Office applications. These external programs are called COM external programs. This article gradually discusses the Office COM external program and introduces how to generate Office COM add-in using Microsoft Visual C # .NET.
Back to top
IDTEXENSIBILITY2 interface
The COM add-in is a process within a process of COM Server or ActiveX Dynamic Link Link Library (DLL), which implements described in the Microsoft Address Designer Type Library (MsadDr.dll).
IDTEXENSIBILITY2 interface. All COM add-in is inherited from this interface, and every way in its five methods must be implemented.
Back to top
ONCONNECTION
Whenever the COM add-in
ONCONNECTION event. The add-on can be connected to the end user or by automation at startup. in case
OnConnection successfully returned, an add-in has been loaded. If an error message is returned, the host application immediately releases its reference to the external program, and the object will be destroyed.
ONCONNECTION uses the following four parameters:
• Application - A reference to the host application object. • ConnectMode - A constant for specifying an external program connection. The add-on can be connected in the following ways:
• EXT_CM_AFTERSTARTUP - The add-in is started by the end user from the COM Add Directions dialog. • EXT_CM_COMMANDLINE - The add-on is connected to the command line. Note that this method does not apply to the COM add-in to generate the Office application. • EXT_CM_EXTERNAL - The add-in is connected by an external application. Note that this method does not apply to the COM external connector to generate the Office application. • EXT_CM_STARTUP - The add-in is started by the host when the application starts. This behavior is controlled by the settings in the registry. • AddInst - A reference to ComadDin objects that reference this additional procedure in the ComadDins collection of the host application. • Custom - An array containing a Variant type value that stores user-defined data.
Back to top
OnDisconnection
When the COM external program is disconnected and will be excited before it is uninstalled from memory
OnDisconnection event. The add-in should perform all resource cleanup operations in this event and restore any changes to the host application.
OnDisConnection uses the following two parameters:
• RemoveMode - a constant that specifies the way an external program is open. The add-on can be disconnected in the following manner:
• EXT_DM_HOSTSHUTDOWN - The add-on is disconnected when the host application is turned off. • EXT_DM_USERCLOSED - The add-in is disconnected by the end user or automation controller. • Custom - An array containing a Variant type value that stores user-defined data. Back to top
Onaddinsupdate
When the registered COM external assembly changes,
ONADDINSUPDATE event. In other words, this event is excited whenever a COM add-in or when it is removed from the host application.
Back to top
OnstartupComplete and Onbeginshutdown
When the host application is busy loading itself or uninstalling itself from memory, it should avoid user interaction, and
OnStartupComplete and
The OnBeginshutDown method is called when the host application has left or is being to enter this state. Only calls when the add-in is connected during the startup
OnStartUpComplete, only the host is disconnected in the closing process to disconnect the connection to the add-in.
Onbeginshutdown.
Since the user interface of the host application is completely active while inspiring these events, they may be the only way to perform certain operations, and they will not be available from other ways.
ONCONNECTION and
These operations are performed in OnDisConnection.
Back to top
COM external program registration
In addition to normal COM registration, the COM add-in need to register themselves every Office application running. In order to register itself to a particular application, the add-in should use its progID as an item name to create a child in the following position:
HKEY_CURRENT_USER / SOFTWARE / Microsoft / Office / OfficeApp / Addins / PROGID
The add-in can provide a value of the display name and a complete description of this location. In addition, the add-in should use a DWORD value called Loadbehavior to specify the desired loading behavior. This value determines how the host application loads an add-in, and it consists of the combination of the following value:
• 0 = disconnect - unloaded. • 1 = Connected - has been loaded. • 2 = bootload - Loads when the application starts. • 8 = DemandLoad - loads only when requested by the user. • 16 = ConnectFirstTime - only one time (when started next time).
Typically 0x03 (Connected | BootLoad) is typically specified.
Achieved
The address of IDTextensibility2 should also specify a DWORD value called CommandLinesafe to point out that the add-in is safe for operations that do not support user interfaces. The value is 0x00 to represent false, and the value is 0x01 indicates true.
Back to top
How to generate a COM add-in using Visual C # .NET
As mentioned above, the Office COM add-on COM server is activated by the Office application through the COM runtime layer. Therefore, in order to develop COM external connections in .NET, the external program components need to be implemented in .NET, then disclose to the COM client (ie Office application) through the COM Interop layer.
To create a COM Add 2 in Visual C # .NET, follow these steps:
1. In Visual C # .NET, create a class library project. 2. Add a reference to the type library that implements IDTextensibility2. The main interface set of this item has appeared under the EXTENSIBILITY name. 3. Add a reference to the Microsoft Office object library. The main interface set of this item has appeared under the Office name. 4. Create a public class in the class library that implements the IDTEXTENSibility2. 5. After generating this class, the library is registered to COM Interop. To do this, you need to generate an assembly that uses a strong name for this class library and then registers it to COM Intero. You can use REGASM.EXE to register .NET components to COM Interop. 6. Create a registry entry to enable the Office application to identify and load an add-in. You can choose to complete all these steps, or you can create a type as
The .NET project of the shared add-in. This will launch the Extended Wizard, which helps you create a COM add-in in .NET.
"Scalability Wizard" will create a Visual C # .NET class library project, and create an implementation.
IDTEXTENSIBILITY2 interface
CNECT class. It also generates implementation
The main code of the empty member of IDTextensibility. This project has references to ExtensIlity and Office assemblies. The project has been selected in the generation settings.
Register COM Interop. The program set key (.snk) file will be generated and in AssemblyInfo.vb files
ASSEMBLYKEYFILE attributes are referenced.
In addition to class library projects, the wizard will also generate a installation project that can be used to deploy COM external connections on other computers. This item can be removed when needed.
Back to top
Step-by-step example
1. On the File menu of Microsoft Visual Studio .NET, click New, and then click Project. 2. In the New Project dialog box, expand other items under the project type, select the extension item, and then select the shared add-in template. 3. Type MyComAddin as the name of the add-in, and then click OK. 4. After the Scalability Wizard appears, follow these steps:
a. On page 1, choose to create an add-in using Visual C #, and then click Next. b. On page 2, select the Host Application below, then click Next:
• Microsoft Word • Microsoft PowerPoint • Microsoft Outlook • Microsoft Excel • Microsoft Accessc. On page 3, enter the name and description of the add-in, then click Next. Note: The name and description of the addr appear in the COM Add-in dialog of Office applications. d. In page 4, select all available options, and then click Next. e. Click Finish. 5. On the project menu, click Add Reference. Click System.Windows.Forms.dll in the Component list, click Select, and then click OK. 6. Add the following code to the namespace list in the Connect class: use system.reflection; 7. Add the following members to the Connect class: private commandbutton mybutton; 8. Implement the members of the IDTextens Ility2 in the Connect class, as follows Image shows: 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_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 exitation one.
Try
{
MyButton = (Commandbarbutton) ostandardbar.controls ["My Custom Button];
}
Catch (Exception)
{
Object omissing = system.reflection.Missing.Value;
MyButton = (Commandbarbutton) OstandardBar.controls.Add (1, OMISSING, OMISING, OMISSING, OMISSING);
MyButton.caption = "My Custom Button";
MyButton.Style = msobuttonstyle.msobuttoncaption;
}
// The Following Items Are Optional, But Recommended.
// the tag printy 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 provides.
MyButton.tag = "My Custom Button";
// The onaction property is optional but recommented.
// IT SHOULD be set to the progid of the add-in, so what if
// the add-in 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 = "!
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 (), "mycom 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 vid mybutton_click (commandbarbutton cmdbutton, ref boult) {
System.windows.Forms.MessageBox.Show ("MyButton Was Clicked", "MyComaddin");
9. Generate and test the COM external connector. To do this, follow these steps:
a. On the Generative menu, click Generate Solution. Note that the .NET class is registered to COM Interop during the process of generating a COM external connector. b. Start a Office application for host applications you selected as an external program (for example, Microsoft Word or Microsoft Excel). c. Once the add-on, you will be excited that its OnStartUpComplete event will be acted, and you will receive a message box. Please turn off the message box. Note that the add-on adds a new custom button that adds a new title "My Custom Button" to the Standard Toolbar. d. Click My Custom Button (My Custom button). The Click event of this button will be processed by an add-in and you receive a message box. Please turn off the message box. e. Exit the Office application. f. When you exit the application, you will inspire the OnBeginsHutDown event and you receive a message box. Close this message box to end the presentation.
