Basic concepts for using Visual Studio to develop and debug apps for Office

apps for Office

Learn how Visual Studio can help you create an app for Office more easily.

Last modified: May 30, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

In this article
Get Started with Visual Studio
Create a project
Modify the settings of the app
Develop the contents of your app
Debug the app
Publish your app for Office
Additional resources

Visual Studio is designed to make it easier for you to develop and debug apps for Office. To learn how, see Development basics. If you’re using Visual Studio 2012, you’ll have to download the Microsoft Office Developer Tools for Visual Studio 2012 from the Office Dev Center. If you’re using Visual Studio 2013, you can get started without having to download anything, or you can download the Microsoft Office Developer Tools for Visual Studio 2013 - March 2014 Update if you want to access the latest features. Just choose a template and select a few options in a wizard and Visual Studio will generate everything you need to run your app immediately. The only thing that you add is the content that you want to appear in the app.

This topic will familiarize you with the Visual Studio experience of creating an app for Office. For example, the generated files in your project, the settings that appear in the manifest editor and how to get the most out of debugging your app in Visual Studio. If you’re ready to create your first app for Office by using Visual Studio, you can go straight to the following topics and come back to this topic later if you want to understand the overall process more.

To get started, use the Apps for Office project template in Visual Studio. The Create app for Office wizard asks you to choose the type of app that you want to create.

To help you decide, see Types of apps for Office.

In Visual Studio 2013, some of the app project templates have been updated to reflect additional functionality:

  • Content apps can now appear in the body of Access and PowerPoint documents, in addition to Excel spreadsheets. You can also choose the Basic Project option to create a basic content app project with minimal starter code, or the Document Visualization Project option (for Access and Excel only) to create a more full-featured content app that includes starter code to visualize and bind to data.

  • Mail apps include options not just for including your app in email messages or appointments, but also for specifying whether the app is available when an email message or appointment is being composed as well as read.

Note Note

In Visual Studio, most options are understandable from their descriptions except for the Email Message checkbox. Use that checkbox if you want to create a mail app that appears not just with mail items, but also with meeting requests, responses, and cancellations.

When you’ve completed the wizard, Visual Studio creates a solution for you. The solution contains two projects: an app project, and an ASP.NET web application project. The following table describes each project.

Project

Description

App project

This project contains only an XML manifest file. This is the file that contains all of the settings that describe your app. These settings help the Office application that is hosting your app determine when your app should be activated and where the app should appear. Visual Studio generates the contents of this file for you so that you can run the project and use your app immediately. You change these settings anytime by using the Manifest editor described later in this topic.

Web application project

This project contains the content pages of your app. It contains all of the files and file references that you need to develop Office-aware HTML and JavaScript pages. While you develop your app, Visual Studio hosts the web application on your local IIS server. When you’re ready to publish your app, you’ll have to find a server to host this project.

To learn more about ASP.NET web application projects, see ASP.NET Web Projects.

To modify the settings of your app, open the manifest editor. The manifest editor is a property page-like editor that enables you to modify the most common settings of your app in a more visual way. You can open the manifest editor from Solution Explorer by expanding the app project node, choosing the folder that contains the XML manifest, and then choosing the ENTER key. 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.

For advanced settings, such as the target locale of the app, edit the XML manifest file of the project directly. In Solution Explorer expand the app project node, expand the folder that contains the XML manifest, choose the XML manifest, and then choose the ENTER key. 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.

The manifest editor has multiple tabs, including General, which contains general app settings such as app name and icon, Activation (Visual Studio 2013 only), which enables you to specify the app's requirements such as required API sets and target applications, and App Domains, which enables you to specify the domains of pages consumed by your app.

General tab settings

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

Property

Corresponding value in the XML manifest file

Description

Display Name

DefaultValue attribute of the DisplayName element.

Name that appears in the UI of the host application. For example, in Excel, when a user chooses Insert, App, this name appears in the list of available apps. This name can also appear as a title above the app.

App type

OfficeApp complexType.

Type of the app. A value of TaskPaneApp indicates that the app appears in the task pane of the Office application. A value of ContentApp indicates that the app appears in the body of a document.

Version

Version element.

Specifies the version of the app.

Provider name

ProviderName element.

Specifies the name of the individual or company that developed the app.

Description

DefaultValue attribute of the Description element.

Description that appears when a user points to the app name in the list of available apps.

Icon

DefaultValue attribute of the IconUrl element.

32 x 32 pixel image that appears for your app in the ribbon of the host application.

High resolution icon (Visual Studio 2013 only)

DefaultValue attribute of the IconUrl element.

64 x 64 pixel image that appears for your app in the ribbon of the host application.

Source location

DefaultValue attribute of the SourceLocation element.

Location of the first page that appears in the app when it is activated in the host application. The default value of this property is the default HTML file of your project.

Requested Height (mail apps only)

RequestedHeight element (DesktopMailAppSettings complexType) (apps for Office 1.0) element.

Number of pixels that the mail app requires as the height of the app pane.

Capabilities (task pane and content apps only)

Capabilities element.

Host application that this app supports.

Permissions

Permissions element.

Permissions required by this app.

Entity Highlighting (mail apps only)

DisableEntityHighlighting element (MailApp complexType) (app manifest schema v1.1) element.

Specifies whether entity highlighting should be turned off for this mail app.

App Domains

AppDomains element.

Specifies additional domains that this app will use to load pages.

Activation Rules (mail apps only)

Rule Element element.

Specifies the list of rules that this collection contains.

Activation tab settings (Microsoft Office Developer Tools for Visual Studio 2013 - March 2014 Update only)

This tab enables you to list the sets of Office JavaScript APIs that must be supported on a target Office application for your app to activate. For example, if your app binds to a table, you'd add the TableBindings API set to the list. This feature helps prevent users from getting ugly JavaScript errors by inadvertently activating your app on an Office host that doesn't support the functionality contained in your app.

The following table describes the fields that appear in the Activation tab of the manifest editor. This tab appears only in content apps and task pane apps.

Property

Description

Required API Sets

Enables you to specify the API set names and the minimum versions required by your app to activate properly. To add an API set, choose it in the drop-down list. To delete an API set, choose it in the list and then choose the Delete key. As you specify API sets, the page displays the Office clients that support that combination of API sets.

Note Note

Because some API sets support only certain Office clients, specifying more API sets decreases the number of Office clients on which your app can activate.

Applications

Enables you to choose the Office applications that you want your app to target. You can target any Office application that's available in Office 365 and Office 2013 SP1, or you can target specific Office applications.

IntelliSense

Enables you to choose whether IntelliSense displays syntax information for all Office JavaScript APIs, or only for APIs in the Required API Sets list.

Summary

The summary section shows where the app will be activated based on your input in the Required API Sets and the Applications sections.

App Domains tab settings

App Domains settings are used when the app needs to communicate with a remote domain (cross-domain communication). The following table describes the fields that appear in the App Domains tab of the manifest editor. These settings enable you to specify the domains that this app will use to load pages.

Property

Description

Enter the URL of a domain

Enables you to enter a URL of a domain that is used by your app. Choose the Add button to add it to the AppDomains list.

AppDomains

The list of app domains that you've specified. You can delete items from the list by choosing them and then choosing the Remove button.

While the app project publishes the settings that describe your app, the web application provides the content that appears in the 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 Office.

As your app becomes more sophisticated, you can add more HTML and JavaScript files. You can use the contents of the default HTML and JavaScript file as examples of the types of references you might want to add to other pages in your project to make them work with your app. The following table describes default HTML and JavaScript files.

File

Description

Home.html

Located in the Home folder of the project, this is default HTML page of the app. This page appears as the first page inside of the app when it is activated in a document, email message or appointment item. This file is convenient because it contains all of the file references that you need to get started. When you are ready to create your first app, just add your HTML code to this file.

Home.js

Located in the Home folder of the project, this is the JavaScript file associated with the Home.js page. You can place any code that is specific to the behavior of the Home.html page in the Home.js file. The Home.js 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 entire app. You can place code that is common to the behavior of multiple pages of your app in the App.js file. The App.js file contains some example code to get you started.

Note 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 app, open the manifest editor, and then point the SourceLocation property to the name of the file.

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

File

Description

Office.css

Contains style definitions that help your app have the same look and feel of the host application.

App.css

Contains any styles that you want to use in multiple pages of your app. This is just a start page. By default, it is empty.

Home.css

Contains any styles that you want to use only in the default HTML file.

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. However, you can use functions in this file directly if you want. The line of code that references this library is commented because you don’t have to explicitly reference the script unless you intend to access the JavaScript API for Office while developing offline. In that case, you’ll want to uncomment both this line and the line that references the office.js file. Both of these lines appear beneath the line To enable offline debugging using a local reference to Office.js, use:

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.

Office.js

Contains the JavaScript API for an app for Office. This file provides your code with an entry point into documents.

For more information about the functions, types, and fields in this file, see the JavaScript API for Office (v1.1).

jquery-<version>.js

Contains a JavaScript library that simplifies HTML document traversing, event handling, animating, and Ajax interactions for rapid web development.

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

Review the build and debug properties

Before you start the solution, verify that Visual Studio will open the host 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 app.

To open the property pages of a project

  1. In Solution Explorer, choose the project name.

  2. On the menu bar, choose View, Properties Window.

The following table describes the properties of the project.

Property

Description

Start Action

Specifies whether to open the document in the Office desktop client or on Internet Explorer.

Start Document

Specifies what document to open when you start the project.

Web Project

Specifies the name of the web project associated with the app.

Email Address (Mail apps only)

Specifies the email address of the user account in Exchange Server with which you want to test the mail app.

EWS Url (Mail apps only)

Exchange Web service URL (For example: https://www.contoso.com/ews/exchange.aspx).

OWA Url (Mail apps only)

Outlook Web App URL (For example: https://www.contoso.com/owa).

User name (Mail apps only)

Specifies the name of your user account in Exchange Server.

Use an existing document to debug the app (Content and task pane apps only)

You can add documents to the app project. If you have a document that contains test data that you want to use with your app, Visual Studio will open that document for you when you start the project.

To use an existing document to debug the app

  1. In Solution Explorer, choose the app project folder.

    Note Note

    Choose the app project and not the web application project.

  2. On the Project menu, choose Add Existing Item.

  3. In the Add Existing Item dialog box, locate and select the document that you want to add.

  4. Choose the Add button to add the document to your project.

  5. In Solution Explorer, open the shortcut menu for the project, and then choose Properties.

    The property pages for the project appear.

  6. In the Start Document list, choose the document that you added to the project, and then choose the OK button to close the property pages.

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

  1. Creates a copy of the XML manifest file and adds it to ProjectName\Output directory. The host application consumes this copy when you start Visual Studio and debug the app.

  2. Creates a set of registry entries on your computer that enable the app to appear in the host application.

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

  1. Modifies the SourceLocation 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).

  2. Starts the web application project in IIS Express.

  3. Opens the host application.

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 an app in Excel, Word, or Project and step through your code

If you set the Start Document property of the app project to Excel or Word, Visual Studio creates a new document and the app appears. If you set the Start Document property of the app project to use an existing document, Visual Studio opens the document, but you have to insert the app manually. If you set the Start Document to Microsoft Project, you also have to insert the app manually.

To show an app for Office in Excel or Word

  1. In Excel or Word, on the Insert tab, choose Apps for Office.

  2. In the list that appears, choose your app.

To show an app for Office in Project

  1. In Project, on the Project tab, choose Apps for Office.

  2. In the list that appears, choose your app.

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

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

  1. In Visual Studio, choose DEBUG, Attach to Process.

  2. In the Attach to Process dialog box, choose all of the available Iexplore.exe processes, and then choose the Attach button.

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

Show:
© 2014 Microsoft