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

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:

• Smart tags

• 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 from Excel projects that are retargeted to the .NET Framework 4. Visual Studio does not automatically remove this attribute 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. The common language runtime (CLR) in the .NET Framework 4 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 Formatting Data in Excel with Various Regional Settings.

To remove the ExcelLocale1033Attribute

1. With the project open in Visual Studio, open Solution Explorer.

2. 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.

3. 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. Therefore, you must remove or comment out the line of code that references this class.

To remove the reference to the ExcelLocal1033Proxy class

1. Open the project in Visual Studio, and then open Solution Explorer.

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

3. 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 Creates Smart Tags

If you have an Excel or Word project that creates smart tags, you must make the following changes to your code if you change the target framework:

• Modify any code that creates smart tag and action objects.

• Modify any code that defines a smart tag class with a custom recognizer.

For more information, see the instructions below.

Creating Smart Tag and Action Objects

You must modify the way that you create smart tag and action objects in your code. In projects that target the .NET Framework 3.5, the smart tag and action types are classes that you can instantiate directly. In projects that target the .NET Framework 4, these types are interfaces that you cannot instantiate directly.

If the target framework of your project is changed to the .NET Framework 4, you must create the smart tag and action objects by using methods that are provided by the Globals.Factory property in your project. For more information, see Smart Tags Architecture.

The following table lists the smart tag and action types and the method to use to create instances of the types in projects that target the .NET Framework 4.

Defining Smart Tag Classes with Custom Recognizers

You must modify your code if you define your own smart tag class with a custom recognizer. In projects that target the .NET Framework 3.5, you derive your class from the Microsoft.Office.Tools.Word.SmartTag or Microsoft.Office.Tools.Excel.SmartTag class. In projects that target the .NET Framework 4, you instead define a class that implements the Microsoft.Office.Tools.Word.ISmartTagExtension or Microsoft.Office.Tools.Excel.ISmartTagExtension interface.

For more information, see Smart Tags Architecture.

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, 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 and Getting Extended Objects from Native Office Objects in Document-Level Customizations.

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, 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 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, 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, 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. 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, 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.

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, 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, 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, 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.

See Also

Concepts

Migrating Office Solutions to the .NET Framework 4

Smart Tags Architecture

Content Controls

Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time

Getting Extended Objects from Native Office Objects in Document-Level Customizations

Adding Controls to Office Documents at Run Time

Global Access to Objects in Office Projects