Partilhar via

Add controls to Office documents at run time

  • Artigo

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

You can add controls to a Microsoft Office Word document and Microsoft Office Excel workbook at run time. You can also remove them at run time. Controls that you add or remove at run time are called dynamic controls.

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

This topic describes the following:

Manage controls at run time by using control collections

To add, get, or remove controls at run time, use helper methods of ControlCollection and ControlCollection objects.

The way that you access these objects depends on the type of project you are developing:

Add controls

The ControlCollection and ControlCollection types include helper methods that you can use to add host controls and common Windows Forms controls to documents and worksheets. Each method name has the format Addcontrol class, where control class is the class name of the control that you want to add. For example, to add a NamedRange control to your document, use the AddNamedRange method.

The following code example adds a NamedRange to Sheet1 in a document-level project for Excel.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Access and delete controls

You can use the Controls property of a Worksheet or Document to iterate through all the controls in your document, including the controls you added at design time. Controls that you add at design time are also called static controls.

You can remove dynamic controls by calling the Delete method of the control, or by calling the Remove method of each Controls collection. The following code example uses the Remove method to remove a NamedRange from Sheet1 in a document-level project for Excel.

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

You cannot remove static controls at run time. If you try to use the Delete or Remove method to remove a static control, a CannotRemoveControlException will be thrown.

Note

Do not programmatically remove controls in the Shutdown event handler of the document. The UI elements of the document are no longer available when the Shutdown event is raised. If you want to remove controls before the document closes, add your code to the event handler for another event, such as BeforeClose or BeforeSave for Word, or BeforeClose, or BeforeSave for Excel.

Add host controls to documents

When you programmatically add host controls to documents, you must provide a name that uniquely identifies the control, and you must specify where to add the control on the document. For specific instructions, see the following topics:

For more information about host controls, see Host items and host controls overview.

When a document is saved and then closed, all dynamically created host controls are disconnected from their events and they lose their data binding functionality. You can add code to your solution to re-create the host controls when the document is reopened. For more information, see Persist dynamic controls in Office documents.

Note

Helper methods are not provided for the following host controls, because these controls cannot be added programmatically to documents: XmlMappedRange, XMLNode, and XMLNodes.

Add Windows Forms controls to documents

When you programmatically add a Windows Forms control to a document, you must provide the location of the control and a name that uniquely identifies the control. The Visual Studio Tools for Office runtime provides helper methods for each control. These methods are overloaded so that you can pass either a range or specific coordinates for the location of the control.

When a document is saved and then closed, all dynamically created Windows Forms controls are removed from the document. You can add code to your solution to re-create the controls when the document is reopened. If you create dynamic Windows Forms controls by using a VSTO Add-in, the ActiveX wrappers for the controls are left in the document. For more information, see Persist dynamic controls in Office documents.

Note

Windows Forms controls cannot be programmatically added to protected documents. If you programmatically unprotect a Word document or Excel worksheet to add a control, you must write additional code to remove the control's ActiveX wrapper when the document is closed. The control's ActiveX wrapper is not automatically deleted from protected documents.

Add custom controls

If you want to add a Control that is not supported by the available helper methods, such as a custom user control, use the following methods:

  • For Excel, use one of the AddControl methods of a ControlCollection object.

  • For Word, use one of the AddControl methods of a ControlCollection object.

    To add the control, pass the Control, a location for the control, and a name that uniquely identifies the control to the AddControl method. The AddControl method returns an object that defines how the control interacts with the worksheet or document. The AddControl method returns a ControlSite (for Excel) or a ControlSite object (for Word).

    The following code example demonstrates how to use the AddControl method to dynamically add a custom user control to a worksheet in a document-level Excel project. In this example, the user control is named UserControl1, and the Range is named range1. To use this example, run it from a Sheetn class in the project.

    Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Use members of custom controls

After using one of the AddControl methods to add a control to a worksheet or document, you now have two different control objects:

  • The Control that represents the custom control.

  • The ControlSite, OLEObject, or OLEControl object that represents the control after it was added to the worksheet or document.

    Many properties and methods are shared between these controls. It is important that you access these members through the appropriate control:

  • To access members that belong only to the custom control, use the Control.

  • To access members that are shared by the controls, use the ControlSite, OLEObject, or OLEControl object.

    If you access a shared member from the Control, it might fail without warning or notification, or it can produce invalid results. Always use methods or properties of the ControlSite, OLEObject, or OLEControl object unless the method or property needed is not available; only then should you reference the Control.

    For example, both the ControlSite class and the Control class have a Top property. To get or set the distance between the top of the control and the top of the document, use the Top property of the ControlSite, not the Top property of the Control.

    ' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

See also