Changes to the Design of Office Projects that Target the .NET Framework 4
Visual Studio 2010 introduces some changes to the design of Office projects that target the .NET Framework 4. 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 the .NET Framework 4. If you have an existing project that you want to update to target the .NET Framework 4, there are several breaking changes that you should be aware of.
Understanding 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, 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, 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:
Updating Excel and Word Projects that You Migrate to the .NET Framework 4
Updating Ribbon Customizations in Office Projects that You Migrate to the .NET Framework 4
Updating Form Regions in Outlook Projects that You Migrate to the .NET Framework 4
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, 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 Programming Application-Level Add-Ins and Programming 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 2010. 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. For further details, see Migrating Office Solutions to the .NET Framework 4.
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. |
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 Updating Excel and Word Projects that You Migrate to the .NET Framework 4. |
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 runtime, handles Ribbon events, or sets the position of a Ribbon component programmatically. For more information, see Updating Ribbon Customizations in Office Projects that You Migrate to the .NET Framework 4. |
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 Updating Form Regions in Outlook Projects that You Migrate to the .NET Framework 4. |
The programming model for smart tags in Excel and Word projects has changed. Smart tags are deprecated in Excel 2010 and Word 2010. For more information, see Smart Tags Overview. |
You must modify any code that creates smart tag and action objects, and code that defines a custom smart tag recognizer. For more information, see Updating Excel and Word Projects that You Migrate to the .NET Framework 4. |
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 Updating Excel and Word Projects that You Migrate to the .NET Framework 4. |
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 Updating Excel and Word Projects that You Migrate to the .NET Framework 4. |
The OLEObject and OLEControl classes have been renamed. |
You must modify any code that uses instances of these classes to use Microsoft.Office.Tools.Excel.ControlSite or Microsoft.Office.Tools.Word.ControlSite objects instead. For more information, see Updating Excel and Word Projects that You Migrate to the .NET Framework 4. |
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. |
See Also
Concepts
Migrating Office Solutions to the .NET Framework 4