Walkthrough: Import a form region that is designed in Outlook

Articolo
02/02/2017

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

This walkthrough demonstrates how to design a form region in Microsoft Office Outlook, and then import the form region into an Outlook VSTO Add-in project by using the New Form Region wizard. Designing the form region in Outlook makes it possible for you to add native Outlook controls to the form region that bind to Outlook data. After you import the form region, you can handle the events of each control.

Applies to: The information in this topic applies to VSTO Add-in projects for Outlook. For more information, see Features available by Office application and project type.

This walkthrough illustrates the following tasks:

Designing a form region by using the form region designer in Outlook.
Importing a form region into an Outlook VSTO Add-in project.
Handling the events of controls on the form region.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Personalize the IDE.

Prerequisites

You need the following components to complete this walkthrough:

An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configure a computer to develop Office solutions.
Outlook 2013 or Outlook 2010.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Personalize the Visual Studio IDE.

Design a form region by using the form region designer in Outlook

In this step you will design a form region in Outlook. You will then the save the form region to an easy-to-find location so that you can import it into Visual Studio.

This example form region completely replaces the usual Task form. It provides a way to track the progress of all tasks that must be completed before the main task can be performed (prerequisite tasks). The form region displays a list of the prerequisite tasks, and shows the completion status for each task in the list. Users can add tasks to the list and remove them. They can also refresh the completion status of each task.

To design a form region by using the form region designer in Outlook

Start Microsoft Office Outlook.
In Outlook, on the Developer tab, click Design a Form. For more information, see How to: Show the developer tab on the ribbon.
In the Design Form box, click Task, and then click Open.
In Outlook, on the Developer tab, in the Design group, click New Form Region.

A new form region opens. If the Field Chooser does not appear, click Field Chooser in the Tools group.
Drag the Subject field and the % Complete field from the Field Chooser to the form region.
In the Tools group, click Control Toolbox to open the Toolbox.
Drag a Label from the Toolbox to the form region. Position the label beneath the Subject and % Complete fields.
Right-click the label, and then click Advanced Properties.
In the Properties window, set the Caption property to This task depends on the following tasks, set the Width property to 200, and then click Apply.
Drag a ListBox control from the Toolbox to the form region. Position the list box beneath the This task depends on the following tasks label.
Select the list box that you just added.
In the Properties window, set Width to 300, and then click Apply.
Drag a Label from the Toolbox to the form region. Position the label beneath the list box.
Select the label that you just added.
In the Properties window, set the Caption property to Select a task to add to the list of dependent tasks, set the Width property to 200, and then click Apply.
Drag a ComboBox control from the Toolbox to the form region. Position the combo box beneath the Select a task to add to the list of dependent tasks label.
Select the combo box that you just added.
In the Properties window, set the Width property to 300, and then click Apply.
Drag a CommandButton control from the Toolbox to the form region. Position the command button next to the combo box.
Select the command button that you just added.
In the Properties window, set Name to AddDependentTask, set Caption to Add Dependent Task, set Width to 100, and then click Apply.
In the Field Chooser, click New.
In the New Field dialog box, type hiddenField in the Name field, and then click OK.
Drag the hiddenField field from the Field Chooser to the form region.
In the Properties window, set Visible to 0 - False, and then click Apply.
In Outlook, on the Developer tab, in the Design group, click the Save button, and then click Save Form Region As.

Name the form region TaskFormRegion and save it to a local directory on your computer.

Outlook saves the form region as an Outlook Form Storage (.ofs) file. The form region is saved with the name TaskFormRegion.ofs.
Exit Outlook.

Create a new Outlook Add-in project

In this step, you will create an Outlook VSTO Add-in project. Later in this walkthrough, you will import the form region into to the project.

To create a new Outlook VSTO Add-in project

In Visual Studio, create an Outlook VSTO Add-in project with the name TaskAddIn.
In the New Project dialog box, select Create directory for solution.
Save the project to the default project directory.

For more information, see How to: Create Office projects in Visual Studio.

Import the form region

You can import the form region that you designed in Outlook into the Outlook VSTO Add-in project by using the New Outlook Form Region wizard.

To import the form region into the Outlook VSTO Add-in project

In Solution Explorer, right-click the TaskAddIn project, point to Add, and then click New Item.
In the Templates pane, select Outlook Form Region, name the file TaskFormRegion, and then click Add.

The NewOutlook Form Region wizard starts.
On the Select how you want to create the form region page, click Import an Outlook Form Storage (.ofs) File, and then click Browse.
In the Existing Outlook Form Region File Location dialog box, browse to the location of TaskFormRegion.ofs, select TaskFormRegion.ofs, click Open, and then click Next.
On the Select the type of form region you want to create page, click Replace-all, and then click Next.

A replace-all form region replaces the entire Outlook form. For more information about form region types, see Create Outlook form regions.
On the Supply descriptive text and select your display preferences page, click Next.
On the Identify the message classes that will display this form region page, in the Which custom message classes will display this form region field, type IPM.Task.TaskFormRegion, and then click Finish.

A TaskFormRegion.cs or TaskFormRegion.vb file is added to your project.

Handle the events of controls on the form region

Now that you have the form region in the project, you can add code that handles the Microsoft.Office.Interop.Outlook.OlkCommandButton.Click event of the button that you added to the form region in Outlook.

Also, add code to the FormRegionShowing event that updates controls on the form region when the form region appears.

To handle the events of controls on the form region

In Solution Explorer, right-click TaskFormRegion.cs or TaskFormRegion.vb, and then click View Code.

TaskFormRegion.cs or TaskFormRegion.vb opens in the Code Editor.

Add the following code to the TaskFormRegion class. This code populates the combo box on the form region with the subject line of each task from the Outlook Tasks folder.

private void populateComboBox()
{
    Outlook.Application Application = new Outlook.Application();
    Outlook.NameSpace outlookNameSpace = Application.GetNamespace("MAPI");
    Outlook.MAPIFolder taskFolder = outlookNameSpace.GetDefaultFolder(
        Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks);
    Outlook.Items taskItems = taskFolder.Items;
    foreach (Outlook.TaskItem task in taskItems)
    {
        if (task.Subject != null)
        {
            comboBox1.AddItem(task.Subject, System.Type.Missing);
        }
    }
    comboBox1.Text = comboBox1.GetItem(0);
}

Private Sub populateComboBox()
    Dim Application As New Outlook.Application()
    Dim outlookNameSpace As Outlook.NameSpace = _
    Application.GetNamespace("MAPI")
    Dim taskFolder As Outlook.MAPIFolder = _
    outlookNameSpace.GetDefaultFolder _
        (Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks)
    Dim taskItems As Outlook.Items = taskFolder.Items
    Dim task As Outlook.TaskItem
    For Each task In taskItems
        If Not (task.Subject Is Nothing) Then
            comboBox1.AddItem(task.Subject, System.Type.Missing)
        End If
    Next task
    comboBox1.Text = comboBox1.GetItem(0)
End Sub

Add the following code to the TaskFormRegion class. This code performs the following tasks:

Locates the Microsoft.Office.Interop.Outlook.TaskItem in the Tasks folder by calling the FindTaskBySubjectName helper method and passing the subject of the desired task. You will add the FindTaskBySubjectName helper method in the next step.
Adds the Microsoft.Office.Interop.Outlook.TaskItem.Subject and Microsoft.Office.Interop.Outlook.TaskItem.PercentComplete values to the dependent task list box.

Adds the subject of the task to the hidden field on the form region. The hidden field stores these values as part of the Outlook item.

    void AddDependentTask_Click()
    {
        Outlook.TaskItem tempTaskItem = FindTaskBySubjectName(comboBox1.Text);
        if (tempTaskItem != null)
        {
            this.listBox1.AddItem(tempTaskItem.PercentComplete.ToString()
+ "% Complete -- " + tempTaskItem.Subject, System.Type.Missing);
            this.olkTextBox3.Text = this.olkTextBox3.Text + "|" + 
                tempTaskItem.Subject;
        }
    }

Private Sub AddDependentTask_Click1() Handles addDependentTask.Click
    Dim tempTaskItem As Outlook.TaskItem = FindTaskBySubjectName _
        (comboBox1.Text)
    If Not (tempTaskItem Is Nothing) Then
        Me.listBox1.AddItem(tempTaskItem.PercentComplete.ToString() & _
            "% Complete -- " & tempTaskItem.Subject, System.Type.Missing)
        Me.olkTextBox3.Text = Me.olkTextBox3.Text & "|" & tempTaskItem.Subject
    End If
End Sub

Add the following code to the TaskFormRegion class. This code provides the helper method FindTaskBySubjectName that was described in the preceding step.

private Outlook.TaskItem FindTaskBySubjectName(string subjectName)
{
    Outlook.Application Application = new Outlook.Application();
    Outlook.NameSpace outlookNameSpace = Application.GetNamespace("MAPI");
    Outlook.MAPIFolder tasksFolder =
        outlookNameSpace.GetDefaultFolder(
    Microsoft.Office.Interop.Outlook.
        OlDefaultFolders.olFolderTasks);
    Outlook.Items taskItems = tasksFolder.Items;
    foreach (Outlook.TaskItem taskItem in taskItems)
    {
        if (taskItem.Subject == subjectName)
        {
            return taskItem;
        }
    }
    return null;
}

Private Function FindTaskBySubjectName(ByVal subjectName As String) _
    As Outlook.TaskItem
    Dim Application As New Outlook.Application()
    Dim outlookNameSpace As Outlook.NameSpace = _
        Application.GetNamespace("MAPI")
    Dim tasksFolder As Outlook.MAPIFolder = _
        outlookNameSpace.GetDefaultFolder _
            (Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks)
    Dim taskItems As Outlook.Items = tasksFolder.Items
    Dim taskItem As Outlook.TaskItem
    For Each taskItem In taskItems
        If taskItem.Subject = subjectName Then
            Return taskItem
        End If
    Next taskItem
    Return Nothing
End Function

Add the following code to the TaskFormRegion class. This code performs the following tasks:

Refreshes the list box on the form region with the current completion status of each dependent task.
Parses the hidden text field to obtain the subject of each dependent task. It then locates each Microsoft.Office.Interop.Outlook.TaskItem in the Tasks folder by calling the FindTaskBySubjectName helper method and passing the subject of each task.

Adds the Microsoft.Office.Interop.Outlook.TaskItem.Subject and Microsoft.Office.Interop.Outlook.TaskItem.PercentComplete values to the dependent task list box.

void RefreshTaskListBox()
{
    listBox1.Clear();
    Outlook.TaskItem tempTaskItem;
    String[] tempArray = olkTextBox3.Text.Split(new Char[] { '|' });

    foreach (string tempString in tempArray)
    {
        tempTaskItem = FindTaskBySubjectName(tempString);
        if (tempTaskItem != null)
        {
            this.listBox1.AddItem(tempTaskItem.PercentComplete.ToString()
                + "% Complete -- " + tempTaskItem.Subject, 
                    System.Type.Missing);
        }
    }
}

Private Sub RefreshTaskListBox()
    listBox1.Clear()
    Dim tempTaskItem As Outlook.TaskItem
    Dim tempArray As [String]() = olkTextBox3.Text.Split(New [Char]() {"|"c})

    Dim tempString As String
    For Each tempString In tempArray
        tempTaskItem = FindTaskBySubjectName(tempString)
        If Not (tempTaskItem Is Nothing) Then
            Me.listBox1.AddItem(tempTaskItem.PercentComplete.ToString() & _
                "% Complete -- " & tempTaskItem.Subject, System.Type.Missing)
        End If
    Next tempString
End Sub

Replace the TaskFormRegion_FormRegionShowing event handler with the following code. This code performs the following tasks:

Populates the combo box on the form region with task subjects when the form region appears.

Calls the RefreshTaskListBox helper method when the form region appears. This displays any dependent tasks that were added to the list box when the item was previously opened.

private void TaskFormRegion_FormRegionShowing
    (object sender, EventArgs e)
{
    populateComboBox();
    RefreshTaskListBox();
    this.addDependentTask.Click += new
    Microsoft.Office.Interop.Outlook.
        OlkCommandButtonEvents_ClickEventHandler(AddDependentTask_Click);

}

Private Sub TaskFormRegion_FormRegionShowing(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles MyBase.FormRegionShowing
    populateComboBox()
    RefreshTaskListBox()
End Sub

Test the Outlook form region

To test the form region, add tasks to the list of prerequisite tasks on the form region. Update the completion status of a prerequisite task, and then view the updated completion status of the task in the prerequisite task list.

To test the form region

Press F5 to run the project.

Outlook starts.
In Outlook, on the Home tab, click New Items, and then click Task.
In the task form, type Dependent Task in the Subject field.
On the Task tab of the Ribbon, in the Actions group, click Save & Close.
In Outlook, on the Home tab, click New Items, click More Items, and then click Choose Form.
In the Choose Form dialog box, click TaskFormRegion, and then click Open.

The TaskFormRegion form region appears. This form replaces the entire task form. The Select a task to add to the list of dependent tasks combo box is populated with other tasks in the Tasks folder.
On the task form, in the Subject field, type Primary Task.
In the Select a task to add to the list of dependent tasks combo box, select Dependent Task, and then click Add Dependent Task.

0% Complete -- Dependent Task appears in the This task depends on the following tasks list box. This demonstrates that you successfully handled the Microsoft.Office.Interop.Outlook.OlkCommandButton.Click event of the button.
Save and close the Primary Task item.
Reopen the Dependent Task item in Outlook.
On the Dependent Task form, change the % Complete field to 50%.
On the Task tab of the Dependent Task Ribbon, in the Actions group, click Save & Close.
Reopen the Primary Task item in Outlook.

50% Complete -- Dependent Task now appears in the This task depends on the following tasks list box.

Next steps

You can learn more about how to customize the UI of an Outlook application from these topics:

To learn more about how to design the appearance of a form region by dragging managed controls onto a visual designer, see Walkthrough: Design an Outlook form region.
To learn about how to customize the Ribbon of an Outlook item, see Customize a ribbon for Outlook.
To learn more about how to add a custom task pane to Outlook, see Custom task panes.

Condividi tramite