Share via

Program document-level customizations

  • Article

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

When you extend Microsoft Office Word or Microsoft Office Excel by using a document-level customization, you can perform the following tasks:

  • Automate the application by using its object model.

  • Add controls to the surface of the document.

  • Call Visual Basic for Applications (VBA) code in the document from the customization assembly.

  • Call code in the customization assembly from VBA.

  • Manage certain aspects of the document while it is on a server that does not have Microsoft Office installed.

  • Customize the user interface (UI) of the application.

    Applies to: The information in this topic applies to document-level projects for Excel and Word. For more information, see Features available by Office application and project type.

    Some aspects of writing code in document-level projects are different from other types of projects in Visual Studio. Many of these differences are caused by the way the Office object models are exposed to managed code. For more information, see Write code in Office solutions.

    For general information about document-level customizations and other types of solutions you can create by using the Office development tools in Visual Studio, see Office solutions development overview (VSTO).

Use the generated classes in document-level projects

When you create a document-level project, Visual Studio automatically generates a class in the project that you can use to start writing your code. Visual Studio generates different classes for Word and Excel:

  • In document-level projects for Word, the class is called ThisDocument by default.

  • Document-level projects for Excel have multiple generated classes: one for the workbook itself, and one for each worksheet. By default, these classes have the following names:

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    The generated class includes event handlers that are called when the document is opened or closed. To run code when the document is opened, add code to the Startup event handler. To run code just before the document is closed, add code to the Shutdown event handler. For more information, see Events in Office projects.

Understand the design of the generated classes

In projects that target the .NET Framework 4 or the .NET Framework 4.5, the host item types in the Visual Studio Tools for Office runtime are interfaces, so the generated classes cannot derive their implementation from them. Instead, the generated classes derive most of their members from the following base classes:

  • ThisDocument: derives from DocumentBase.

  • ThisWorkbook: derives from WorkbookBase.

  • Sheet n: derives from WorksheetBase.

    These base classes redirect all calls to their members to internal implementations of the corresponding host item interfaces in the Visual Studio Tools for Office runtime. For example, if you call the Protect method of the ThisDocument class, the DocumentBase class redirects this call to the internal implementation of the Document interface in the Visual Studio Tools for Office runtime.

Access the object model of the host application

To access the object model of the host application, use members of the generated class in your project. Each of these classes corresponds to an object in the object model of Excel or Word, and they contain most of the same properties, methods, and events. For example, the ThisDocument class in a document-level project for Word provides most of the same members as the Document object in the Word object model.

The following code example shows how to use the Word object model to save the document that is part of a document-level customization for Word. This example is intended to be run from the ThisDocument class.

Me.Save()

this.Save();

To do the same thing from outside the ThisDocument class, use the Globals object to access the ThisDocument class. For example, you can add this code to an actions pane code file if you want to include a Save button in the actions pane UI.

Globals.ThisDocument.Save()

Globals.ThisDocument.Save();

Because the ThisDocument class obtains most of its members from the Document host item, the Save method that is called in this code is really the Save method of the Document host item. This method corresponds to the Save method of the Document object in the Word object model.

For more information about using the object models of Word and Excel, see Word object model overview and Excel object model overview.

For more information about the Globals object, see Global access to objects in Office projects.

Add controls to documents

To customize the UI of the document, you can add Windows Forms controls or host controls to the document surface. By combining different sets of controls and writing code, you can bind the controls to data, collect information from the user, and respond to user actions.

Host controls are classes that extend some of the objects in the Word and Excel object model. For example, the ListObject host control provides all of the functionality of the ListObject in Excel. However, the ListObject host control also has additional events and data binding capabilities.

For more information, see Host items and host controls overview and Windows forms controls on Office documents overview.

Combine VBA and document-level customizations

You can use VBA code in a document that is part of a document-level customization. You can call VBA code in the document from the customization assembly, and you can also configure your project to enable VBA code in the document to call code in the customization assembly.

For more information, see Combine VBA and document-level customizations.

Manage documents on a server

You can manage several different aspects of document-level customizations on a server that does not have Microsoft Office Word or Microsoft Office Excel installed. For example, you can access and modify data in the data cache of the document. You can also manage the customization assembly that is associated with the document. For example, you can programmatically remove the assembly from the document so that the document no longer runs your code, or you can programmatically attach an assembly to a document.

For more information, see Manage documents on a server by using the ServerDocument class.

Customize the user interface of Microsoft Office applications

You can customize the UI of Word and Excel in the following ways by using a document-level customization:

Get extended objects from native Office objects in document-level customizations

Many event handlers for Office events receive a native Office object that represents the workbook, worksheet, or document that raised the event. In some cases, you might want to run some code only if the workbook or document in your document-level customization raised the event. For example, in a document-level customization for Excel, you might want to run some code when the user activates one of the worksheets in the customized workbook, but not when the user activates a worksheet in some other workbook that happens to be open at the same time.

When you have a native Office object, you can test whether that object has been extended into a host item or host control in a document-level customization. Host items and host controls are types provided by the Visual Studio Tools for Office runtime that add functionality to objects that exist natively in the Word or Excel object models (called native Office objects). Collectively, host items and host controls are also called extended objects. For more information about host items and host controls, see Host items and host controls overview.

Understand the GetVstoObject and HasVstoObject methods

To test a native Office object, use the HasVstoObject and GetVstoObject methods in your project:

  • Use the HasVstoObject method if you want to determine whether the native Office object has an extended object in your customization. This method returns true if the native Office object has an extended object, and false otherwise.

  • Use the GetVstoObject method if you want to get the extended object for a native Office object. This method returns a ListObject, Workbook, Worksheet, or Document object if the specified native Office object has one. Otherwise, GetVstoObject returns null. For example, the GetVstoObject method returns a Document if the specified Document is the underlying object for the document in your Word document project.

    In document-level projects, you cannot use the GetVstoObject method to create a new Workbook, Worksheet, or Document host item at run time. You can use this method only to access existing host items that are generated in your project at design time. If you want to create new host items at run time, you must develop a VSTO Add-in project. For more information, see Programmatic limitations of host items and host controls and Extend Word documents and Excel workbooks in VSTO Add-ins at run time.

Use the GetVstoObject and HasVstoObject methods

To call the HasVstoObject and GetVstoObject method, use the Globals.Factory.GetVstoObject or Globals.Factory.HasVstoObject method, and pass in the native Word or Excel object (such as a Document or Worksheet) that you want to test.

See also