This topic has not yet been rated - Rate this topic

Using Visual Studio to develop a mail app for Outlook

apps for Office

Published: February 26, 2013

How to

Learn how to use Visual Studio 2012 to develop a mail app for Outlook 2013.

In this article
Create a mail app
Modify the settings of your mail app
Develop the contents of your mail app
Debug the mail app
Publish your mail app

You can use Visual Studio to create mail apps that appear next to email messages and appointment items. Just choose a template and select a few options in a wizard. Visual Studio generates everything you need to run your app immediately. The only thing that you have to add is the content that appears in the app.

This topic focuses on the Visual Studio experience. However, it does contain sample code. The sample used in this topic enables shows a Bing map of the first address that appears in the body of an email message. s.

Create a mail app

To get started, create an Apps for Office project in Visual Studio.

To create a mail app project

Start Visual Studio.
On the menu bar, choose File, New, Project.

The New Project dialog box opens.
In the templates pane, under the node for the language you want to use, expand Office SharePoint.
In the list of project types for Apps, choose Apps for Office.
In the Name box, enter a name for the project.

By default, the project name is also used as the solution name.
In the Location box, enter the path where you want to create the project, and then choose the OK button.

The Create app for Office dialog box opens.
In the Create app for Office dialog box, choose Mail app in:.
- If you want the mail app to work with mail items, meeting requests, responses, and cancellations, , select the Email Message checkbox.
- If you want the mail to work with appointment items, select Appointment checkbox.
Click Finish.

When you complete the wizard, Visual Studio creates a solution. The solution contains a mail app project and an ASP.NET Web application project.

The mail app project contains only an XML manifest file. Visual Studio generates the contents of this file for you. Therefore, you can run the project and see your mail app next to Outlook items without adding anything else to this file.
The ASP.NET web application project contains the content pages of your mail app. It contains all of the files and file references that you need to develop Outlook-aware HTML and JavaScript pages. While you develop your mail app, Visual Studio hosts the Web application on your local IIS server.

If you want to learn more about ASP.NET Web application projects, see ASP.NET Web Projects.

Modify the settings of your mail app

Your mail app contains settings that describe how your mail app should be activated when an end user installs and uses it. You can use a property page-like editor to provide values for the most common settings such as which page appears when the app is activated or the text used to describe your app to potential users.

For advanced settings, such as the activation rules that govern when an app appears, edit the XML manifest file of the project directly.

The manifest editor

You can open the manifest editor from Solution Explorer. Just expand the mail app project node, and choose the folder that contains the XML manifest, and then press the ENTER key.

The following table describes the fields that appear in the manifest editor.

Property	Corresponding value in the XML manifest file	Description
Display Name	DefaultValue attribute of the DisplayName element (OfficeApp complexType) (apps for Office) element.	The label for the app button. For mail apps, the app button appears in the app pane when Outlook activates the mail app.
App type	The OfficeApp complexType.	The value of this property is always Mail App.
Version	The Version element.	Specifies the version of the mail app.
Provider name	The ProviderName element.	Specifies the name of the individual or company that developed the mail app.
Description	DefaultValue attribute of the Description element (OfficeApp complexType) (apps for Office) element.	A string that typically explains the purpose of the app.
Icon	DefaultValue attribute of the IconUrl element (OfficeApp complexType) (apps for Office) element.	The URI of an image file that should be used to represent the app.
Source Location	DefaultValue attribute of the SourceLocation element (TaskPaneAppSettings complexType) (apps for Office) element.	The location of the first page that appears when Outlook activates the mail app.
Requested Height	TheRequestedHeight element (DesktopMailAppSettings complexType) (apps for Office) element.	The number of pixels that the mail app requires as the height of the app pane.
Permissions	The Permissions element (TaskPaneApp complexType) (apps for Office) element.	The permissions required by this mail app.
Entity Highlighting	The DisableEntityHighlighting element (MailApp complexType) (apps for Office) element.	Specifies whether entity highlighting should be turned off for this mail app.
App Domains	The AppDomains element.	Specifies additional domains that this app will use to load pages.
Activation Rules	The Rule Element element.	Specifies the list of rules that this collection contains.

The XML manifest

You can open the XML manifest file from Solution Explorer. Just expand the mail app project node, expand the folder that contains the XML manifest, and then choose the XML manifest.

Visual Studio generates the contents of this file for you. You can point to any element in the file to view a tooltip that describes the purpose of the element. For a complete list of descriptions, see Apps for Office XML manifest overview.

Develop the contents of your mail app

While the mail app project publishes the settings that describe your mail app, the Web application provides the content that appears in the mail app.

The Web application project contains a default html page and JavaScript file that you can use to get started. The project also contains a JavaScript file that is common to all pages that you add to your project. These files are convenient because they contain references to other JavaScript libraries including the JavaScript API for apps.

File	Description
Home.html	Located in the Home folder of the project, this is default HTML page of the mail app. This page appears as the first page inside of the mail app when it is activated in an email message or appointment item. This file is convenient because it contains all of the file references that you need to get started.
Home.js	Located in the Home folder of the project, this is the default JavaScript file of the page. This file contains some example code to get you started.
App.js	Located in the App folder of the project, this is the default JavaScript file of the app. This file contains some example code to get you started.

Note
You do not have to use these files. Feel free to add other files to the project and use those instead. If you want another html file to appear as the initial page of the mail app, open the manifest editor, and then point the SourceLocation property to the name of the file.

The default html file

When it’s time to create the UI of your mail app, the default html page is a great place to start. You can open the default html file from Solution Explorer. Just expand the Web application project folder, expand the App folder, expand the Home folder, then choose Home.html. Then, on the View menu, choose Code.

The <head> element of the page refers to several files. The following table describes each of them.

File	Description
Styles/Base/Office.css	Contains style definitions that help your mail app have the same look and feel of the Office application.
Styles/App.css	Contains any styles that you want to add. This is just a start page. By default, it is empty.
Scripts/Lib/MicrosoftAjax.js	Defines language extensions that are supported by the Microsoft Ajax library. This file is included in the project because the Office.js file consumes it. But you can use functions in this file directly if you want. For more information about the functions, types, and fields of the library, see Microsoft Ajax Library Client Reference. To learn about Microsoft Ajax in general, see Inside the Microsoft Ajax Library.
Scripts/Lib/Office.js Office.js	Contains the JavaScript API for a mail app. This file provides your code with an entry point into documents. For more information about the functions, types, and fields in this file, see JavaScript API references for apps for Office.
Scripts/jquery-1.6.2.js	Contains a JavaScript library that simplifies HTML document traversing, event handling, animating, and Ajax interactions for rapid web development.

Add code to the default html file

The following HTML creates a section that shows a Bing map.

HTML

    </div>
    <script type="text/javascript" src="https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=7.0&s=1"></script>
    <div id='myMap'></div>

The default JavaScript file

You can open the default JavaScript file of your page from Solution Explorer. Just expand the Web application project folder, expand the App folder, expand the Home folder, and then chooseHome.js. Then, on the View menu, choose Code.

This file contains a declaration of the initialize event of the Office object. You can place any code inside this event that you want to run when the app is loaded.

Add code to the default JavaScript file

The following JavaScript adds the functions that are called in the default html file. This code shows a Bing map in cases where a mail item contains an address. A pushpin appears for the location of the address.

Note
To run this sample, you’ll have to obtain a Bing maps key. For more information, see Getting a Bing Maps Key.

JavaScript

var map = null;
(function () {
    "use strict";

    // The Office initialize function must be run each time a new page is loaded
    Office.initialize = function (reason) {
   // Checks for the DOM to load using the jQuery ready function.        
   $(document).ready(function () {
            app.initialize();

            GetMap();
        });
    };
    function GetMap() {

        var entities = Office.context.mailbox.item.getEntities
            (Office.MailboxEnums.EntityType.Address);

        var AppId = "<Replace with your BingMaps developer key>";
       
        var myMap = $('#myMap')[0];

        if (null != entities && null != entities.addresses && undefined != entities.addresses) {

            map = new Microsoft.Maps.Map(myMap,
            {
                credentials: AppId
            });

            $.ajax({
                type: 'GET',
                url: 'http://dev.virtualearth.net/REST/v1/Locations?query=' + entities.addresses[0] + '&key=' + AppId + '&jsonp=?',
                dataType: 'jsonp',
                success: function (result) {
                    var bbox = result.resourceSets[0].resources[0].bbox;

                    var viewBoundaries = Microsoft.Maps.LocationRect.fromLocations
                       (new Microsoft.Maps.Location(bbox[0], bbox[1]),
                    new Microsoft.Maps.Location(bbox[2], bbox[3]));

                    map.setView({ bounds: viewBoundaries });

                    // Add a pushpin at the found location.
                    var location = new Microsoft.Maps.Location
                        (result.resourceSets[0].resources[0].point.coordinates[0],

                    result.resourceSets[0].resources[0].point.coordinates[1]);

                    var pushpin = new Microsoft.Maps.Pushpin(location);

                    map.entities.push(pushpin);
                },
                error: function (result) {
                    app.showNotification("oops", "Unable to display map");
                        
 

                }
            });

        }

    }

})();

Debug the mail app

When you are ready to start your mail app, review build and debug related properties, and then start the solution.

Review the build and debug properties

Before you start the solution, it’s a good idea to make sure that Visual Studio will open the Office application that you want. That information appears in the property pages of the project along with several other properties that relate to building and debugging the mail app.

To open the property pages of a project, perform the following steps:

In Solution Explorer, choose the project name.
On the menu bar, choose View, Properties Window.

The following table describes some of the most important properties of the project.

Property	Description
Start Action	Specifies what application to open when you start the project.
Email Address	Specifies the email address of the user account in Exchange Server with which you want to test the mail app.
EWS Url	The Exchange Web service Url (For example: https://www.contoso.com/ews/exchange.aspx).
OWA Url	The Outlook Web App Url (For example: https://www.contoso.com/owa).
User name	Specifies the name of your user account in Exchange Server.

Start the solution

Visual Studio will automatically build the solution when you start it. You can start the solution from the Menu bar by choosing Debug, Start.

Note
If script debugging isn't enabled in Internet Explorer, you won't be able to start the debugger in Visual Studio. You can enable script debugging by opening the Internet Options dialog box, choosing the Advanced tab, and then clearing the Disable Script Debugging (Internet Explorer) and Disable Script Debugging (Other) check boxes.

Visual Studio builds the project and performs the following actions.

Creates a copy of the XML manifest file and adds it to ProjectName\Output directory. Outlook consumes this copy when you start Visual Studio and debug the mail app.
Creates a set of registry entries on your computer that enable the mail app to appear in Outlook.
Builds the Web application project, and then deploys it to the local IIS Web server (http://localhost).

After Visual Studio builds the project, Visual Studio performs the following actions.

Modifies the SourceLocation element (TaskPaneAppSettings complexType) (apps for Office) element of the XML manifest file by replacing the ~remoteAppUrl token with the fully qualified address of the start page (For example: http://localhost/MyAgave.html).
Starts the Web application project in IIS Express.
Starts Outlook.

Visual Studio doesn't show validation errors in the OUTPUT window when you build the project. Visual Studio reports errors and warnings in the ERRORLIST window as they occur. Visual Studio also reports validation errors by showing wavy underlines (known as squiggles) of different colors in the code and text editor. These marks notify you of problems that Visual Studio detected in your code. For more information, see Code and Text Editor. For more information about how to enable or disable validation, see the following topics:

To review the validation rules of the XML manifest file in your project, see Apps for Office XML manifest overview.

Show the mail app in Outlook and step through your code

To view the app in Outlook, open an email message or appointment item.

Outlook activates the app for the item as long as the activation criteria are met. The app bar appears at the top of the Inspector window or Reading Pane, and your mail app appears as a button in the app bar.

To view your mail app, choose the button for your mail app.

In Visual Studio, you can set break-points. Then, as you interact with your mail app and step through the code in your HTML, JavaScript, and C# or VB code files.

You can also change your code and review the effects of those changes in your mail app without having to close the Office app and start the project again. In Outlook, just open the shortcut menu for the mail app, and then choose Reload.

Modify code and continue to debug the app without having to start the project again

You can change your code and review the effects of those changes in your app without having to close the host application and start the project again. After you change your code, open the shortcut menu for the app, and then choose Reload. When you reload the app it becomes disconnected with the Visual Studio debugger. Therefore, you can view the effects of your change, but you cannot step through your code again until you attach the Visual Studio debugger to all of the available iexplore.exe processes.

To attach the Visual Studio debugger to all of the available iexplore.exe processes

In Visual Studio, choose DEBUG, Attach to Process.
In the Attach to Process dialog box, choose all of the available iexplore.exe processes, and then choose the Attach button.

Publish your mail app

For more information about how to publish your app, see How to: Publish an app for Office

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Additions

ADD