Updating Excel and Word Projects that You Migrate to the .NET Framework 4 or the .NET Framework 4.5

Article
10/31/2012

If you have an Excel or Word project that uses any of the following features, you must modify your code if the target framework is changed to the .NET Framework 4 or the .NET Framework 4.5:

GetVstoObject and HasVstoObject methods
Generated classes in document-level projects
Windows Forms controls on documents
Word content control events
OLEObject and OLEControl classes
Controls.Item(Object) property
Collections that derive from CollectionBase

You must also remove the Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute and references to the Microsoft.Office.Tools.Excel.ExcelLocale1033Proxy class from Excel projects that are retargeted to the .NET Framework 4 or the .NET Framework 4.5. Visual Studio doesn’t remove this attribute or the class reference for you.

Removing the ExcelLocale1033 Attribute From Excel Projects

The Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute has been removed from the portion of the Visual Studio 2010 Tools for Office Runtime that is used for solutions that target the .NET Framework 4 or the .NET Framework 4.5. The common language runtime (CLR) in the .NET Framework 4 and the .NET Framework 4.5 always passes locale ID 1033 to the Excel object model, and you can no longer use this attribute to disable this behavior. For more information, see Globalization and Localization of Excel Solutions.

To remove the ExcelLocale1033Attribute

With the project open in Visual Studio, open Solution Explorer.
Under the Properties node (for C#) or the My Project node (for Visual Basic), double-click the AssemblyInfo code file to open it in the code editor.

Note

In Visual Basic projects, you must click the Show All Files button in Solution Explorer to see the AssemblyInfo code file.
Locate the Microsoft.Office.Tools.Excel.ExcelLocale1033Attribute and either remove it from the file or comment it out.
```
<Assembly: ExcelLocale1033Proxy(True)>
```
```
[assembly: ExcelLocale1033Proxy(true)]
```

Removing a Reference to the ExcelLocal1033Proxy class

Projects that were created by using Microsoft Visual Studio 2005 Tools for the Microsoft Office System instantiate the Excel Microsoft.Office.Interop.Excel.Application object by using the Microsoft.Office.Tools.Excel.ExcelLocale1033Proxy class. This class has been removed from the portion of the Visual Studio 2010 Tools for Office Runtime that’s used for solutions that target the .NET Framework 4 or the .NET Framework 4.5. Therefore, you must remove or comment out the line of code that references this class.

To remove the reference to the ExcelLocal1033Proxy class

Open the project in Visual Studio, and then open Solution Explorer.
In Solution Explorer, open the shortcut menu for ThisAddin.cs (for C#) or ThisAddin.vb (for Visual Basic), and then choose View Code.

In the Code Editor, in the VSTO generated code region, remove or comment out the following line of code.

Me.Application = CType(Microsoft.Office.Tools.Excel.ExcelLocale1033Proxy.Wrap(GetType(Excel.Application), Me.Application), Excel.Application)

this.Application = (Excel.Application)Microsoft.Office.Tools.Excel.ExcelLocale1033Proxy.Wrap(typeof(Excel.Application), this.Application);

Updating Code that Uses the GetVstoObject and HasVstoObject Methods

In projects that target the .NET Framework 3.5, the GetVstoObject or HasVstoObject methods are available as extension methods on one of the following native objects in your project: Microsoft.Office.Interop.Word.Document, Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet, or Microsoft.Office.Interop.Excel.ListObject. When you call these methods, you do not need to pass a parameter. The following code example demonstrates how to use the GetVstoObject method in a Word add-in that targets the .NET Framework 3.5.

Dim vstoDocument as Microsoft.Office.Tools.Word.Document = _
    Globals.ThisAddIn.Application.ActiveDocument.GetVstoObject()

Microsoft.Office.Tools.Word.Document vstoDocument = 
    Globals.ThisAddIn.Application.ActiveDocument.GetVstoObject();

In projects that target the .NET Framework 4 or the .NET Framework 4.5, you must modify your code to access these methods in one of the following ways:

You can still access these methods as extension methods on Microsoft.Office.Interop.Word.Document, Microsoft.Office.Interop.Excel.Workbook, Microsoft.Office.Interop.Excel.Worksheet, or Microsoft.Office.Interop.Excel.ListObject objects. However, you must now pass the object returned by the Globals.Factory property to these methods.
```
Dim vstoDocument as Microsoft.Office.Tools.Word.Document = _
    Globals.ThisAddIn.Application.ActiveDocument.GetVstoObject(Globals.Factory)
```
```
Microsoft.Office.Tools.Word.Document vstoDocument = 
    Globals.ThisAddIn.Application.ActiveDocument.GetVstoObject(Globals.Factory);
```

You can alternatively access these methods on the object that is returned by the Globals.Factory property. When you access these methods in this way, you must pass the native object that you want to extend to the method.

Dim vstoDocument as Microsoft.Office.Tools.Word.Document = _
    Globals.Factory.GetVstoObject(Globals.ThisAddIn.Application.ActiveDocument)

Microsoft.Office.Tools.Word.Document vstoDocument = 
    Globals.Factory.GetVstoObject(Globals.ThisAddIn.Application.ActiveDocument);

For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

Updating Code that Uses Instances of the Generated Classes in Document-Level Projects

In document-level projects that target the .NET Framework 3.5, the generated classes in the projects derive from the following classes in the Visual Studio Tools for Office runtime:

ThisDocument: Microsoft.Office.Tools.Word.Document
ThisWorkbook: Microsoft.Office.Tools.Excel.Workbook
Sheetn: Microsoft.Office.Tools.Excel.Worksheet
Chartn: Microsoft.Office.Tools.Excel.ChartSheet

In projects that target the .NET Framework 4 or the .NET Framework 4.5, the types in the Visual Studio Tools for Office runtime listed above are interfaces, instead of classes. The generated classes in projects that target the .NET Framework 4 or the .NET Framework 4.5 derive from the following new classes in the Visual Studio Tools for Office runtime:

ThisDocument: Microsoft.Office.Tools.Word.DocumentBase
ThisWorkbook: Microsoft.Office.Tools.Excel.WorkbookBase
Sheetn: Microsoft.Office.Tools.Excel.WorksheetBase
Chartn: Microsoft.Office.Tools.Excel.ChartSheetBase

If code in your project refers to an instance of one of the generated classes as the base class that it derives from, you must modify the code.

For example, in an Excel Workbook project that targets the .NET Framework 3.5, you might have a helper method that performs some work on instances of the generated Sheetn classes in your project.

Private Sub DoSomethingToSheet(ByVal worksheet As Microsoft.Office.Tools.Excel.Worksheet)
    ' Do something to the worksheet object.
End Sub

private void DoSomethingToSheet(Microsoft.Office.Tools.Excel.Worksheet worksheet)
{
    // Do something to the worksheet object.
}

If you retarget the project to the .NET Framework 4 or the .NET Framework 4.5, you must make one of the following changes to your code:

Modify any code that calls the DoSomethingToSheet method to pass the Base property of a Microsoft.Office.Tools.Excel.WorksheetBase object in your project. This property returns a Microsoft.Office.Tools.Excel.Worksheet object.
```
DoSomethingToSheet(Globals.Sheet1.Base)
```
```
DoSomethingToSheet(Globals.Sheet1.Base);
```

Modify the DoSomethingToSheet method parameter to expect a Microsoft.Office.Tools.Excel.WorksheetBase object instead.

Private Sub DoSomethingToSheet(ByVal worksheet As Microsoft.Office.Tools.Excel.WorksheetBase)
    ' Do something to the worksheet object.
End Sub

private void DoSomethingToSheet (Microsoft.Office.Tools.Excel.WorksheetBase worksheet)
{
    // Do something to the worksheet object.
}

Updating Code that Uses Windows Forms Controls on Documents

You must add a using (C#) or Imports (Visual Basic) statement for the Microsoft.Office.Tools.Excel or Microsoft.Office.Tools.Word namespace to the top of any code file that uses the Controls property to add Windows Forms controls to the document or worksheet programmatically.

In projects that target the .NET Framework 3.5, the methods that add Windows Forms controls (such as the AddButton method) are defined in the Microsoft.Office.Tools.Excel.ControlCollection and Microsoft.Office.Tools.Word.ControlCollection classes.

In projects that target the .NET Framework 4 or the .NET Framework 4.5, these methods are extension methods that are available on the Controls property. To use these extension methods, the code file in which you use the methods must have a using or Imports statement for the Microsoft.Office.Tools.Excel or Microsoft.Office.Tools.Word namespace. This statement is generated automatically in new projects that target the .NET Framework 4 or the .NET Framework 4.5. However, this statement is not added automatically in projects that target the .NET Framework 3.5, so you must add it when you retarget the project.

For more information, see Adding Controls to Office Documents at Run Time.

Updating Code that Handles Word Content Control Events

In projects that target the .NET Framework 3.5, events of Word content controls are handled by the generic EventHandler<TEventArgs> delegate. In projects that target the .NET Framework 4 or the .NET Framework 4.5, these events are handled by other delegates.

The following table lists the Word content control events and the delegates that are associated with them in projects that target the .NET Framework 4 or the .NET Framework 4.5.

Event	Delegate to use in .NET Framework 4 and .NET Framework 4.5 projects
Added	ContentControlAddedEventHandler
ContentUpdating	ContentControlContentUpdatingEventHandler
Deleting	ContentControlDeletingEventHandler
Entering	ContentControlEnteringEventHandler
Exiting	ContentControlExitingEventHandler
StoreUpdating	ContentControlStoreUpdatingEventHandler

Updating Code that Uses the OLEObject and OLEControl Classes

In projects that target the .NET Framework 3.5, you can add custom controls (such as Windows Forms user controls) to a document or worksheet by using the Microsoft.Office.Tools.Excel.OLEObject and Microsoft.Office.Tools.Word.OLEControl classes.

In projects that target the .NET Framework 4 or the .NET Framework 4.5, these classes have been replaced by the Microsoft.Office.Tools.Excel.ControlSite and Microsoft.Office.Tools.Word.ControlSite interfaces. You must modify code that refers to Microsoft.Office.Tools.Excel.OLEObject and Microsoft.Office.Tools.Word.OLEControl to instead refer to Microsoft.Office.Tools.Excel.ControlSite and Microsoft.Office.Tools.Word.ControlSite. Other than the new names, these controls behave the same way that they do in projects that target the .NET Framework 3.5.

For more information, see Adding Controls to Office Documents at Run Time.

Updating Code that Uses the Controls.Item(Object) Property

In projects that target the .NET Framework 3.5, you can use the Item(Object) property of the Microsoft.Office.Tools.Word.Document.Controls or Microsoft.Office.Tools.Excel.Worksheet.Controls collection to determine whether a document or worksheet has a specified control.

In projects that target the .NET Framework 4 or the .NET Framework 4.5, the Item(Object) property has been removed from these collections. To determine whether a document or worksheet contains a specified control, use the Contains(System.Object) method of the Document.Controls or Worksheet.Controls collection instead.

For more information about the Controls collection of documents and worksheets, see Adding Controls to Office Documents at Run Time.

Updating Code that Uses Collections that Derive from CollectionBase

In projects that target the .NET Framework 3.5, several collection types in the Visual Studio Tools for Office runtime derive from the CollectionBase class, such as Microsoft.Office.Tools.SmartTagCollection, Microsoft.Office.Tools.Excel.ControlCollection, and Microsoft.Office.Tools.Word.ControlCollection.

In projects that target the .NET Framework 4 or the .NET Framework 4.5, these collection types are now interfaces that do not derive from CollectionBase. Some members are no longer available on these collection types, such as Capacity, List, and InnerList.

Share via