Creating Managed FrontPage 2003 Add-ins in C#

 

Lisa Wollin
Microsoft Corporation

August 2004

Applies to:
    Microsoft Office FrontPage 2003

Summary:   Learn how to create a managed add-in for FrontPage 2003 using Visual Studio .NET and Visual C# .NET. The download that accompanies this article contains the form and code files for the Insert Images add-in project discussed in this article. (12 printed pages)

Download odc_fpManagedFrontPageAddins.exe

Contents

Introduction
Understanding .NET Dependencies
Getting Started
Adding Your Own Code
Finalizing Your Code
Deploying Your Add-in
Troubleshooting Your Add-in
Working with the Download
Conclusion

Introduction

Similar to macros but more powerful, add-ins allow you to extend the built-in functionality of Microsoft Office FrontPage 2003. You can create COM add-ins in Microsoft Visual Basic 6.0 or Microsoft Visual C++ 6.0, or you can create managed add-ins in any of the languages that use the Microsoft .NET Framework, such as Microsoft Visual Basic .NET or Microsoft Visual C# .NET.

When you create managed add-ins for FrontPage2003, you can use the tools, classes, and programming languages that are part of the Microsoft .NET Framework. This article shows you how to create a managed add-in for FrontPage in C# and assumes a general knowledge of the .NET Framework and a functional knowledge of the C# programming language.

This article explains what you need to know to create your own managed add-ins for FrontPage and provides extensive resources for more information.

Note   The example in this article requires that you have the .NET Framework installed; Visual Studio .NET with Visual C#; and FrontPage 2003, including the .NET Programmability Support option.

Understanding .NET Dependencies

COM add-ins use COM technology and the Visual Basic for Applications (VBA) COM object models to communicate with FrontPage. Managed add-ins use .NET technology; however, because the FrontPage and Office object models are stored in COM DLLs, the .NET Framework requires an interop assembly (IA) to access them. For more information, see Interoperating with Unmanaged Code.

Visual Studio .NET creates an IA when you add a reference to a COM component if a primary interop assembly (PIA) is not available. PIAs are vendor-supplied IAs that provide access to COM object models from managed code. Microsoft supplies PIAs for all Office System applications, including FrontPage, and we encourage you to use the PIAs that are installed with FrontPage when developing managed add-ins rather than the IA that Visual Studio creates. Microsoft specifically designed the PIAs for accessing the Office object models.

PIAs are stored in the Assembly folder in the Windows installation folder. The default path is C:\WINDOWS\assembly. In this folder, you can find two PIAs for FrontPage. One is named Microsoft.Office.Interop.FrontPage, and the other is named Microsoft.Office.Interop.FrontPageEditor. Together, these two files provide access to the FrontPage object models in managed code.

You should verify that you have these files installed. If you do not, you need to install them before continuing.

Note   The Office PIAs are installed by default only if you have Visual Studio .NET already installed on your computer. If you installed FrontPage 2003 or the Microsoft Office 2003 System prior to installing Visual Studio .NET and did not specifically choose to install .NET Programmability Support when you installed FrontPage, you need to install the PIAs by using Add or Remove Programs to change the FrontPage installation to include .NET Programmability Support.

After you verify that you have the FrontPage PIAs, you are ready to create your first managed FrontPage add-in. This article uses portions of the sample Insert Image add-in included in the download for demonstration purposes but does not describe all of the code contained in the add-in. However, the complete code for the add-in is included in the download and is thoroughly commented.

Note   A thorough discussion of the .NET Framework, C#, and the FrontPage object models is beyond the scope of this article. For more information, see the Microsoft Developer Network (MSDN) library, the Microsoft .NET Framework Developer Center, the Microsoft Visual C# Developer Center, and the FrontPage Developer Center. You can also find information in the following articles about working with the .NET Framework in Office applications and creating managed Office add-ins:
Introducing .NET to Office Developers
Creating Office Managed COM Add-ins with Visual Studio .NET
Building Microsoft Office Add-ins with Visual C# .NET and Visual Basic .NET

Getting Started

For the .NET Framework to communicate with Office applications, you need to include the IDTExtensibility2 interface in your add-in projects. You can manually add the methods for this interface to an add-in project, but if you are working in Visual Studio .NET, you can create what is called a Shared Add-in. When you create a Shared Add-in, Visual Studio sets up your project with the necessary Extensibility interface references and stubs out code for each of the members. Then you can add the code that is unique to your add-in.

Creating Your First Add-in Project

The following steps show you how to create a Shared Add-in project in Visual Studio .NET using the C# language.

  1. Start Visual Studio.

  2. On the File menu, point to New, and click Project. The New Project dialog box appears.

  3. In the Project Types list, double-click the Other Projects folder, and click the Extensibility Projects folder.

  4. In the Templates list, click Shared Add-In.

  5. In the Name box, type the name of your add-in. For the project in this article, use "FPAddin".

  6. In the Location box, type the path to the folder in which you want to save your FrontPage add-in project or click Browse and navigate to the folder path.

  7. Click OK. The Extensibility Wizard appears.

  8. Click Next.

  9. On page 1 of the Visual Studio Add-In Wizard, click Create an Add-in using Visual C#.

  10. Click Next.

  11. On page 2 of the Visual Studio Add-In Wizard, clear the check boxes for all Office applications except FrontPage.

  12. Click Next.

  13. On page 3 of the Visual Studio Add-In Wizard, type "FrontPage Add-in" in the What is the name of your Add-in box, and type "Sample managed add-in for FrontPage" in the What is the description for your Add-in box.

  14. Click Next.

  15. On page 4 of the Visual Studio Add-In Wizard, select I would like my Add-in to load when the host application loads. This ensures that your add-in is available to users when they start FrontPage. Optionally you can select My Add-in should be available to all users of the computer it was installed on, not just the person who installs it, which ensures that your add-in is available to all users of the computer.

    Note   Managed add-ins do not always display in the COM Add-Ins dialog box. For more information, see Microsoft Knowledge Base Article - 316723 PRB:Visual Studio .NET Shared Add-in Is Not Displayed in Office COM Add-ins Dialog Box.

  16. Click Next.

  17. Page 5 of the Visual Studio Add-In Wizard should resemble Figure 1. You can use the Back button to redo any of the previous steps.

    Click here to see larger image

    Figure 1. Summary page of Visual Studio Add-in Wizard (Click picture to view larger image)

  18. Click Finish. Visual Studio creates your add-in project.

Connect Class

When Visual Studio creates your add-in project, you see the code for a custom class called Connect. The Connect class implements the IDTExtensibility2 interface that your add-in needs to communicate with FrontPage. Within the Connect class the following functions are stubbed out for you.

Table 1. Functions of the Connect class

Function Name Description
OnConnection Runs when FrontPage loads an add-in.
OnAddinsUpdate Runs when FrontPage loads or unloads an add-in.
OnStartUpComplete Runs when FrontPage finishes starting up.
OnBeginShutdown Runs when FrontPage starts to shut down.
OnDisconnection Runs when FrontPage unloads an add-in.

At the bottom of the class code are two class variables: applicationObject and addInInstance. Use the applicationObject variable to access the FrontPage application and the addInInstance variable to access the add-in project.

For more information on the IDTExtensibility2 interface, see the following resources:

Adding Your Own Code

After Visual Studio finishes generating the code for your add-in project, you are ready to add your own code.

Adding a Reference to a Type Library

Before you can access the FrontPage object models, you need to add a reference to the FrontPage type libraries. The Shared Add-in Wizard adds a reference to the core Office object library, but you need to manually add references for each application in which you want your add-in to work. In this case, you need a reference to the FrontPage Web and Page object models.

To add a reference

  1. On the Project menu, click Add Reference.
  2. Click the COM tab.
  3. Scroll through the list and select Microsoft FrontPage 6.0 Page Object Reference Library and Microsoft FrontPage 6.0 Web Object Reference Library. (Hold down the Ctrl key to select both items.)
  4. Click Select.
  5. Click OK.

After you add the references, the Solution Explorer shows the FrontPage object models in the list of references, as shown in Figure 2.

Figure 2. Solution Explorer in Visual Studio .NET

Adding a Using Alias

Once you add references to the FrontPage object models, you can use them in your code. You can add using directives so that you don't need to type a fully qualified namespace path to the object that you want to use. Generally, you can type a using directive similar to the using directive that Visual Studio generates for the Office core object model, as shown in the following code.

using Microsoft.Office.Core;

The following example shows similar directives for the FrontPage object models.

using Microsoft.Office.Interop.FrontPage;
using Microsoft.Office.Interop.FrontPageEditor;

However, if you add the preceding directive for the FrontPage Web object library, the C# compiler generates errors when you compile your add-in project. This is because the FrontPage Web object model has a System object, and the compiler confuses the System object in the FrontPage object model with the System namespace in the .NET Framework. To remove this confusion and the resulting errors, assign an alias to an object library in the using directive. The following code shows how to do this.

using fpweb = Microsoft.Office.Interop.FrontPage;

This allows you to access the objects in the FrontPage Web object library by using fpweb instead of the fully qualified namespace path of Microsoft.Office.Interop.FrontPage.

Note   The C# compiler does not require using aliases, but they are a convenient way to access object models in your C# projects and, as in the case of the FrontPage Web object model, can resolve collisions with objects of the same name in different namespaces.

Accessing the FrontPage Application

When you first create your add-in project, Visual Studio generates code for the OnConnection method. The OnConnection method has an application parameter of type object. This parameter returns an instance of the add-in's host application. Because you are creating a FrontPage add-in, you know this parameter provides access to the FrontPage application. The OnConnection method also assigns the application parameter to the class variable, applicationObject. You would use the applicationObject variable to access the FrontPage application.

Creating a Custom Form

Creating a form for a custom add-in is the same as creating a form for a Windows application. The following steps show you how to do this:

  1. Right-click the add-in project in the Solution Explorer.
  2. Click Add.
  3. Click Add Windows Form.
  4. In the Add New Item dialog box, type the filename for your form in the Name box. For the Insert Image add-in, type "InsertImageForm.cs".
  5. Click Open. Visual Studio adds a new Windows form to your add-in project.

The finished form for the Insert Images add-in is shown in Figure 3.

Click here to see larger image

Figure 3. Finished form for the Insert Images add-in (Click picture to view larger image)

You can add this form to your add-in project by inserting the frmInsertImage.cs file that is included in the download for this article.

Note   If you created an InsertImageForm.cs file using the preceding steps, right click it in the Solution Explorer and select Delete before adding the finished form.

To add the Insert Image form to your project

  1. Right-click the add-in project in the Solution Explorer.
  2. Click Add.
  3. Click Add Existing Item.

Accessing the Form in FrontPage

After you have a form in your add-in, you need a way to access it from within FrontPage. You can do this by adding new menus, menu items, toolbars, and toolbar controls. The CommandBars property of the Application object provides access to the Office core CommandBars collection and related objects. For more information on the CommandBars objects, see the following resources:

For the Insert Images add-in, you need one button on the main toolbar. To add this button, you add code to the OnStartUpComplete method to create a toolbar button.

Note   If you haven't already done so, add to your add-in project the Connect.cs file that is included in the download so that you see the completed code for the OnStartUpComplete method.

To facilitate command bar control for users, you need to add a global variable for the toolbar button so that the button is active and available as long as your add-in is loaded. In addition, you need an event handler for the button's click event. In the code for the button's click event, you show the Insert Image form.

Accessing FrontPage Events

FrontPage has a variety of events that you may want to capture in your add-in. For example, the toolbar button for the Insert Image add-in should be available only if a Web site and a Web page are open. This is partly because the add-in's form lists all the image files within a Web site. Attempting to use the add-in when a Web site and a page are not open would cause a run-time error. To eliminate the errors, you can set the toolbar button's Enabled property to false when you first create it so that it is disabled by default.

Then you can use the OnPageWindowActivate event to enable the button when a page is opened or a new page is created. To ensure that you don't end up with a situation in which the button is enabled when a Web site or page is not open, you need to use the OnPageClose event to disable the button every time a page is closed. The easiest time to create the code for the event procedure is when you insert the event handler.

To add an event

  1. Type the event handler code. For example, if you want to add an event handler for the OnPageClose event, in the OnStartUpComplete function type "appFP.OnPageClose +=". Visual Studio displays the AutoComplete ToolTip, as shown in Figure 4.

    Click here to see larger image

    Figure 4. Creating an event handler for the OnPageClose event (Click picture to view larger image)

  2. Press Tab. Visual Studio inserts the event handler code and allows you to insert the name of the event procedure, as shown in Figure 5.

    Click here to see larger image

    Figure 5. Specifying the name of the event procedure (Click picture to view larger image)

  3. At this point, you can press Tab again to accept the default event procedure name or type a different name for the event procedure. The event procedure for the OnPageClose event in the Insert Image add-in is called DisableButton, so type "DisableButton" to replace the highlighted text. Your code resembles Figure 6.

    Click here to see larger image

    Figure 6. Preparing to generate the completed event handler (Click picture to view larger image)

  4. Press Tab to create the event procedure. Visual Studio inserts the event code into your project.

Finalizing Your Code

To reduce errors, it is always a good idea to explicitly destroy objects after you are finished with them. Although one advantage of the .NET Framework is that it performs automatic garbage collection, FrontPage add-ins use COM Interop and therefore can hold object references the same as in a COM environment.

Within the add-in form, you should add cleanup code for global objects within the Closing event. The following code in the Closing event cleans up all the global objects in the Insert Images form as well as explicitly destroying a connection between the image file and the image in the picture box that displays the image.

private void InsertImageForm_Closing(object sender, _
System.ComponentModel.CancelEventArgs e)
{
    //Explicitly destroy local variables.
    this.selectedImageObject.Dispose();
    this.appFP = null;

    //Dispose image control so that add-in doesn't hold onto the image file.
    if (this.selectedImage != null && this.selectedImage.Image != null)
    {
        this.selectedImage.Image.Dispose();
    }

    //Explicitly garbage collect free memory from disposed objects.
    System.GC.Collect();
}

Notice that at the end of the preceding code, the code calls the Collect method of the System.GC class (garbage collection). This action explicitly collects any memory that was freed by destroying the objects.

In addition, in the OnDisconnection method for the IDTExtensibility2 interface, you should explicitly destroy any global objects that the Connect class uses to access the FrontPage application.

If you look at the code in the Connect.cs file, you notice that the OnDisconnection method explicitly deletes the toolbar button. This is important because if you don't explicitly delete the button when you unload the add-in,

  • The button is displayed even if the add-in is not loaded; and
  • Every time the add-in is loaded, it creates a new button so that users end up with multiple buttons, only one of which may work.

In addition, the OnDisconnection method explicitly destroys the global FrontPage Application object variable, fpWeb, as well as the two object variables, applicationObject and addInInstance, that Visual Studio creates by default. After you have done that, you can perform an explicit garbage collection of all freed resources.

For more information on garbage collection, see the following resources:

Deploying Your Add-in

After you finished writing the code for your add-in, you need to package it for others to install and use. To prepare your project for release, you should first change the Active Solution Configuration for your project (Build menu, Configuration Manager) to "Release."

By default, Visual Studio configures the add-in project to compile the add-in and the setup projects separately. You should specify that both the setup project and the add-in are compiled at the same time. Then if you make a change to the add-in code, you don't need to remember to recompile the setup project separately.

To configure your project to compile both the add-in and the setup projects simultaneously

  1. On the Build menu, click Configuration Manager.
  2. In Active Solution Configuration, select Release.
  3. In the Project Contexts list, select the boxes in the Build column.
  4. Click Close.

In the setup project, you can specify how the installation program runs and which dialog boxes users see during installation. You can also specify what, if any, dependencies are included when installing your application. To see the list of dependencies, open the Solution Explorer (View menu).

When Visual Studio first creates a Shared Add-In project, it includes references to the following two assemblies:

  • Extensibility.dll .NET assembly (located at C:\Program Files\Microsoft Visual Studio .NET\Common7\IDE\PublicAssemblies\Extensibility.dll)
  • Office.dll .NET assembly (located at C:\WINDOWS\Microsoft.NET\Framework\v1.0.3705\Office.dll)

In addition, as you add references to your add-in project, Visual Studio adds the corresponding dependencies to the setup project. These assemblies are necessary for the add-in to run on users' machines and must be installed with the add-in.

The .NET Framework (dotnetfxredist_x86.msm) and the stdole.dll .NET assembly are excluded from the setup file but are required on users' computers for the managed add-in to work.

Important   The setup program won't run if the .NET Framework is not already installed on a user's computer. If you are uncertain whether your users have the .NET Framework installed, you should instruct them to download and install it or include the .NET Framework redistributable file with your add-in. Any users who do not have the .NET Framework installed on their computers receive a message indicating that the .NET Framework is required. For more information, see Using Visual Studio .NET 2003 to Redistribute the .NET Framework.

For more information on creating and modifying setup projects, see the following resources.

After you configure your setup project the way you want it, click the Build menu and then Build SetupProject (where SetupProject is the name of the setup project, which for the Insert Images add-in is "FPAddInSetup"). Visual Studio creates a setup project folder for the setup program, and places the setup.exe and MSI file within the Debug folder of the setup project folder, or the Release folder if you are compiling a release build. Distribute these two files so that your users can install the add-in on their computers.

Troubleshooting Your Add-in

As with most development projects, you will likely encounter problems along the way. Some of those problems may be a result of code errors, but there may also be problems during run time if users attempt to use your add-in in a way that you didn't expect. The following sections help you to handle potential problems with your add-in.

Stepping Through the Code

By default, when you first create your add-in project, you can't step through your add-in project code. You can compile the code and start FrontPage and play around with the UI, but to step through the code you need to specify that FrontPage is the startup application.

To set FrontPage as the startup application

  1. On the Project menu, click Properties.
  2. In the property pages for the project, select All Configurations from the Configuration box.
  3. Click Configuration Properties and then Debugging.
  4. In the list of properties in the Start Action area, select the Start Application property and click More.
  5. Navigate to the FRONTPG.EXE file located in the Office program folder.
  6. Click Open.

Now when you click Run, FrontPage starts, and you can set breakpoints and step through the code line by line using the Visual Studio Step Into (F11) and Step Over (F10) functions.

Using Error Handling

No matter how much you test and step through your code, your users may encounter problems that you didn't anticipate. Unexpected errors can stop your add-in, or even FrontPage, from functioning. To reduce the possibility of breaking your add-in and possibly crashing FrontPage, you should add error handling.

To provide error handling in your code, use a try...catch statement. The try block contains the code that you want to run. The catch block contains the code that you want to run if the code encounters an error.

The Exception object in the .NET Framework provides an extensive list of possible errors, or exceptions. You can look for and handle certain exceptions, or you can handle all exceptions the same. You must determine which method is best for your application.

Ideally every procedure that you write would have error handling, but minimally, you should provide error handling at key spots in your code. For example, the Insert Images add-in code provides error handling for the Click event for the OK button on the Insert Images form. This is because the page may not be ready for programmatically inserting HTML code. The error handling in the code accounts for the possibility that the ParseCodeChanges method may not prepare the page for inserting code while the page is displayed in code view.

For more information on error handling, see the following resources:

Known Issue

In some situations, the FrontPage application may remain in memory after FrontPage has shut down. There is no solution for this issue at this time; however, you can minimize this problem in a couple of ways.

First, as explained previously in Finalizing Your Code, ensure that you explicitly destroy all global objects after you use them. In addition, as with the PictureBox control in the Insert Images add-in, ensure that none of your controls retain a hold on resources that you have used in your add-in. You can also walk through your code and verify that no object references remain active when the add-in shuts down.

Second, add code to explicitly collect freed memory by using the Collect method of the System.GC class at key points in your code, such as when a form is closed or the add-in is unloaded.

Although the preceding suggestions may not completely fix this issue, they do improve how managed add-ins function in FrontPage and facilitate shutting down and unloading managed add-ins.

Working with the Download

When you download and install the download file associated with this article, you get all the form and code files for the Insert Images add-in project. The best way to use these files is to create a local Shared Add-in project in Visual Studio and add the InsertImageForm.cs, Image.cs, and Connect.cs files to your new project. You need to add references to the System.Windows.Forms and System.Drawing components. You can then compile the project and step through the code as well as access the add-in in FrontPage.

Note   In some cases, you may not be able to access the design surface of the form. In this case, you need to add a form to your project and then replace it with the form file from the download. To do this, add a new form to your project with the filename InsertImageForm.cs. Then copy the InsertImageForm.cs file from the download into your project folder, replacing the form that you created

Conclusion

This article has shown how to create your own managed add-ins for FrontPage and provided many resources that you can use to help you. There are many reasons why you might want to create an add-in for FrontPage, and creating add-ins that use the .NET Framework provides a great amount of flexibility. If you create an add-in, you can share it and promote it in the FrontPage Add-in Center.