Worksheet host item

The Worksheet host item is a type that extends the Worksheet type from the primary interop assembly for Excel. The Worksheet host item provides all of the same properties, methods, and events as a Worksheet object, but it also exposes additional events and acts as a container for host controls and Windows Forms controls.

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

In document-level projects, you can add Worksheet host items to your project at design time. In VSTO Add-in projects, you can generate Worksheet host items at run time.

Understand worksheet host items in document-level projects

When you create a document-level project for Excel, Visual Studio automatically creates three Worksheet host items in the project. The default names of the worksheets are Sheet1, Sheet2, and Sheet3. If you create a project based on an existing workbook, the number of host items depends on the number of worksheets in the workbook.

These worksheet classes give you access to members of the Worksheet host item to perform basic tasks in your customization, such as modifying the contents of a worksheet. You can also use these classes to add controls to worksheets. 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. For more information, see Program document-level customizations.

The worksheet classes provide a location in which you can start writing code in your project. Because the class provides all of the same properties, methods, and events as the Worksheet object in the primary interop assembly for Excel, you can also use these classes to access the object model of Excel. For more information, see Excel object model overview.

In document-level projects, you can add additional Worksheet host items to the project at design time by adding a new worksheet to the workbook in the designer.

Rename worksheets

In a document-level project, you can rename the worksheets in the Visual Studio designer, but this only changes the display name of the worksheet. The programmatic name is still the default name of the worksheet. If you rename the worksheet in the Properties window, only the programmatic name is changed.

Limitations of the worksheet host item in document-level projects

You cannot create new Worksheet host items at run time in a document-level project. If you create a new Excel worksheet at run time, it will be of the type Worksheet. Because it is not a host item, it cannot contain any host controls or Windows Forms controls. For more information about creating documents at run time, see How to: Programmatically add new worksheets to workbooks.

Understand worksheet host items in VSTO Add-in projects

In application-level projects, you can generate a Worksheet host item at run time for any worksheet that is open in Excel. You can use the Worksheet host item to add controls to the associated worksheet, or to handle events that are not available on Worksheet objects.

To generate a Worksheet host item, use the GetVstoObject method. For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at run time.