Updating Form Regions in Outlook Projects that You Migrate to the .NET Framework 4 or the .NET Framework 4.5

  • Article

If the target framework of an Outlook add-in project with a form region is changed to the .NET Framework 4 or the .NET Framework 4.5, you must make some changes to the generated form region code and to any code that instantiates certain form region classes at run time.

Updating the Generated Form Region Code

If the target framework of the project is changed to the .NET Framework 4 or the .NET Framework 4.5, you must change the generated form region code. The changes you make are different for form regions that you designed in Visual Studio and form regions that you imported from Outlook. For more information about the differences between these types of form regions, see Creating Outlook Form Regions.

To update the generated code for a form region that you designed in Visual Studio

  1. Open the form region code-behind file in the code editor. This file is named YourFormRegion.Designer.cs or YourFormRegion.Designer.vb. To see this file in Visual Basic projects, click the Show All Files button in Solution Explorer.

  2. Modify the declaration of the form region class so that it derives from FormRegionBase instead of Microsoft.Office.Tools.Outlook.FormRegionControl.

  3. Modify the constructor of the form region class as shown in the following code examples.

    The following code example shows the constructor of a form region class in a project that targets the .NET Framework 3.5.

    Public Sub New(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion)
    MyBase.New(formRegion)
    Me.InitializeComponent()
End Sub

    public FormRegion1(Microsoft.Office.Interop.Outlook.FormRegion formRegion)
    : base(formRegion)
{
    this.InitializeComponent();
}

    The following code example shows the constructor of a form region class in a project that targets the .NET Framework 4.

    Public Sub New(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion)
    MyBase.New(Globals.Factory, formRegion)
    Me.InitializeComponent()
End Sub

    public FormRegion1(Microsoft.Office.Interop.Outlook.FormRegion formRegion)
    : base(Globals.Factory, formRegion)
{
    this.InitializeComponent();
}

  4. Modify the signature of the InitializeManifest method as shown below. Make sure that you do not modify the code in the method; this code represents form region settings that you applied in the designer. In Visual C# projects, you must expand the region that is named Form Region Designer generated code to see this method.

    The following code example shows the signature of the InitializeManifest method in a project that targets the .NET Framework 3.5.

    Private Shared Sub InitializeManifest(ByVal manifest As Microsoft.Office.Tools.Outlook.FormRegionManifest)

    ' Do not change code in this method.
End Sub

    private static void InitializeManifest(Microsoft.Office.Tools.Outlook.FormRegionManifest manifest)
{
    // Do not change code in this method.
}

    The following code example shows the signature InitializeManifest method in a project that targets the .NET Framework 4.

    Private Shared Sub InitializeManifest(ByVal manifest As Microsoft.Office.Tools.Outlook.FormRegionManifest, 
    ByVal factory As Microsoft.Office.Tools.Outlook.Factory)

    ' Do not change code in this method.
End Sub

    private static void InitializeManifest(Microsoft.Office.Tools.Outlook.FormRegionManifest manifest, 
    Microsoft.Office.Tools.Outlook.Factory factory)
{
    // Do not change code in this method.
}

  5. Add a new Outlook Form Region item to your project. Open the code-behind file for the new form region, locate the YourNewFormRegionFactory and WindowFormRegionCollection classes in the file, and copy these classes to the Clipboard.

  6. Delete the new form region you added to your project.

  7. In the code-behind file of the form region that you are updating to work in the retargeted project, locate the YourOriginalFormRegionFactory and WindowFormRegionCollection classes and replace them with the code that you copied from the new form region.

  8. In the YourNewFormRegionFactory and WindowFormRegionCollection classes, search for all references to the YourNewFormRegion class and change each reference to the YourOriginalFormRegion class instead. For example, if the form region you are updating is named SalesDataFormRegion and the new form region you created in step 5 is named FormRegion1, change all references of FormRegion1 to SalesDataFormRegion.

To update the generated code for a form region that you imported from Outlook

  1. Open the form region code-behind file in the code editor. This file is named YourFormRegion.Designer.cs or YourFormRegion.Designer.vb. To see this file in Visual Basic projects, click the Show All Files button in Solution Explorer.

  2. Modify the declaration of the form region class so that it derives from ImportedFormRegionBase instead of Microsoft.Office.Tools.Outlook.ImportedFormRegion.

  3. Modify the constructor of the form region class as shown in the following code examples.

    The following code example shows the constructor of a form region class in a project that targets the .NET Framework 3.5.

    Public Sub New(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion)
    MyBase.New(formRegion)
End Sub

    public ImportedFormRegion1(Microsoft.Office.Interop.Outlook.FormRegion formRegion)
    : base(formRegion)
{
    this.FormRegionShowing += new System.EventHandler(this.TaskFormRegion_FormRegionShowing);
    this.FormRegionClosed += new System.EventHandler(this.TaskFormRegion_FormRegionClosed);
}

    The following code example shows the signature of the constructor of a form region class in a project that targets the .NET Framework 4.

    Public Sub New(ByVal formRegion As Microsoft.Office.Interop.Outlook.FormRegion)
    MyBase.New(Globals.Factory, formRegion)
End Sub

    public ImportedFormRegion1(Microsoft.Office.Interop.Outlook.FormRegion formRegion)
    : base(Globals.Factory, formRegion)
{
    this.FormRegionShowing += new System.EventHandler(this.TaskFormRegion_FormRegionShowing);
    this.FormRegionClosed += new System.EventHandler(this.TaskFormRegion_FormRegionClosed);
}

  4. For each line of code in the InitializeControls method that initializes a control in the form region class, modify the code as shown below.

    The following code example shows how to initialize a control in a project that targets the .NET Framework 3.5. In this code, the GetFormRegionControl method has a type parameter that specifies the type of the control that is returned.

    Me.olkTextBox1 = Me.GetFormRegionControl(Of Microsoft.Office.Interop.Outlook.OlkTextBox)("OlkTextBox1")

    this.olkTextBox1 = this.GetFormRegionControl<Microsoft.Office.Interop.Outlook.OlkTextBox>("OlkTextBox1");

    The following code example shows how to initialize a control in a project that targets the .NET Framework 4. In this code, the GetFormRegionControl method does not have a type parameter. You must cast the return value to the type of the control that you are initializing.

    Me.olkTextBox1 = CType(GetFormRegionControl("OlkTextBox1"), Microsoft.Office.Interop.Outlook.OlkTextBox)

    this.olkTextBox1 = (Microsoft.Office.Interop.Outlook.OlkTextBox)GetFormRegionControl("OlkTextBox1");

  5. Add a new Outlook Form Region item to your project. Open the code-behind file for the new form region, locate the YourNewFormRegionFactory and WindowFormRegionCollection classes in the file, and copy these classes to the Clipboard.

  6. Delete the new form region you added to your project.

  7. In the code-behind file of the form region that you are updating to work in the retargeted project, locate the YourOriginalFormRegionFactory and WindowFormRegionCollection classes and replace them with the code that you copied from the new form region.

  8. In the YourNewFormRegionFactory and WindowFormRegionCollection classes, search for all references to the YourNewFormRegion class and change each reference to the YourOriginalFormRegion class instead. For example, if the form region you are updating is named SalesDataFormRegion and the new form region you created in step 5 is named FormRegion1, change all references of FormRegion1 to SalesDataFormRegion.

Instantiating Form Region Classes

You must modify any code that dynamically instantiates certain form region classes. In projects that target the .NET Framework 3.5, you can instantiate form region classes such as Microsoft.Office.Tools.Outlook.FormRegionManifest directly. In projects that target the .NET Framework 4 or the .NET Framework 4.5, these classes are interfaces that you cannot instantiate directly.

If the target framework of your project is changed to the .NET Framework 4 or the .NET Framework 4.5, you must instantiate the interfaces by using methods that are provided by the Globals.Factory property. For more information about the Globals.Factory property, see Global Access to Objects in Office Projects.

The following table lists the form region types and the method to use to instantiate the types in projects that target the .NET Framework 4 or the .NET Framework 4.5.

Type

Factory method to use

FormRegionCustomAction

CreateFormRegionCustomAction

FormRegionInitializingEventArgs

CreateFormRegionInitializingEventArgs

FormRegionManifest

CreateFormRegionManifest

See Also

Concepts

Migrating Office Solutions to the .NET Framework 4 or the .NET Framework 4.5

Other Resources

Creating Outlook Form Regions