Changes to the design of Office projects that target the .NET Framework 4 or the .NET Framework 4.5
Applies to: 
Visual Studio 
Visual 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
Starting in Visual Studio 2010, Visual Studio introduced some changes to the design of Office projects that target the .NET Framework 4 or later. If you are familiar with Office projects in previous versions of Visual Studio, you should be aware of these changes before you develop Office projects that target those versions of the .NET Framework 4.0 or later. By default, all projects that you create by using Visual Studio 2013 or later target the .NET Framework 4.0 or later.
The following sections describe these Office project design changes.
Understand the interface-based design of the Visual Studio 2010 Tools for Office runtime
When you develop an Office project that targets the .NET Framework 4 or later, most of the types that you use in the Visual Studio 2010 Tools for Office runtime are interfaces. This is a major change from previous versions of the Visual Studio Tools for Office runtime, where these types are classes. For example, when you target the .NET Framework 4 or later, the Worksheet and Document types are interfaces instead of classes. For more information, see Visual Studio Tools for Office runtime overview.
For any types that you could instantiate directly in previous versions of the Visual Studio Tools for Office runtime, you now use methods of the Globals.Factory object to get instances of these types. For example, to get an object that implements the SmartTag interface, use the Globals.Factory.CreateSmartTag method. For more information, see the following topics:
New base classes in Office projects
The new interface-based design of the Visual Studio 2010 Tools for Office runtime affects the generated classes in Office projects, such as ThisDocument, ThisWorkbook, and ThisAddIn. In Office projects that target the .NET Framework 3.5 and previous versions of the framework, these generated classes derive from classes in the Visual Studio Tools for Office runtime such as Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Worksheet, and Microsoft.Office.Tools.AddIn. In projects that target the .NET Framework 4 or later, these Visual Studio Tools for Office runtime classes are now interfaces. Therefore the generated classes in Office projects can no longer derive their implementation from them. Instead, the generated classes derive from new base classes such as DocumentBase, WorksheetBase, and AddInBase. For more information, see Program VSTO Add-ins and Program document-level customizations.
The base classes are not part of the Visual Studio Tools for Office runtime redistributable. Instead, they are defined in utilities assemblies that are included with Visual Studio. These assemblies are copied to the output folder when you build Office projects and must be deployed with your solution. For more information about the utilities assemblies, see Assemblies in the Visual Studio Tools for Office runtime.
Breaking changes in Office projects that are retargeted to the .NET Framework 4
The following table lists the main breaking changes you can encounter in Office projects that are retargeted to the .NET Framework 4 or later. For further details, see Migrate Office solutions to the .NET Framework 4 or later.
| Breaking change | Consequence |
|---|---|
| The SecurityTransparentAttribute is no longer used or supported in Office projects. | You must remove this attribute from the AssemblyInfo code file in Office projects that you upgrade from Visual Studio 2008. For more information, see Required changes to run Office projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
| The ExcelLocale1033Attribute is no longer used or supported in Excel projects. | You must remove this attribute from the AssemblyInfo code file in Excel projects. For more information, see Update Excel and Word projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
| The programming model of Ribbon (Visual Designer) project items has changed. | You must modify the code-behind file for any ribbon items in your project. You must also modify any code that instantiates ribbon controls at run time, handles ribbon events, or sets the position of a ribbon component programmatically. For more information, see Update Ribbon customizations in Office projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
| The programming model of Outlook form regions has changed. | You must modify the code-behind file for any form regions in your project and any code that instantiates certain form region classes at run time. For more information, see Update form regions in Outlook projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
| The programming model for smart tags in Excel and Word projects has changed. Smart tags are deprecated in Excel 2010 and Word 2010. | If your solution uses smart tags, errors will occur when you build the project. Because smart tags are deprecated in Excel 2010 and Word 2010, you must remove the tags before you can test and debug the solution in Visual Studio 2013 or later. |
The syntax of the GetVstoObject and HasVstoObject methods has changed |
You must pass the Globals.Factory object to these methods when you access them on native objects from the primary interop assemblies (PIAs), or you can access these methods on the object that is returned by the Globals.Factory property in your project. For more information, see Update Excel and Word projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
| The events of Word content controls are associated with new delegates. | You must modify any code that handles events of Word content controls to specify the new delegates. For more information, see Update Excel and Word projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
The OLEObject and OLEControl classes have been renamed. |
You must modify any code that uses instances of these classes to use ControlSite or ControlSite objects instead. For more information, see Update Excel and Word projects that you migrate to the .NET Framework 4 or the .NET Framework 4.5. |
Host item classes, such as ThisWorkbook, Sheetn, ThisDocument, and ThisAddIn, no longer provide a Dispose method that you can override. |
You must move any code in the Dispose method override to the Shutdown event handler in the host item class, for example, ThisAddIn_Shutdown, and remove the Dispose method override from your host item class. |