Office Add-ins XML manifest

Office Add-ins

Create or edit the manifest XML file for an Office Add-in.

Last modified: August 07, 2015

Applies to: Access apps for SharePoint | apps for Office | Excel | Office Add-ins | Outlook | PowerPoint | Project | Word

Learn more about supported hosts and other requirements.

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

In this article
Required elements
Sample manifest V1.1 XML files
Validate the Office Add-ins manifest
Specify domains you want to open in the add-in window
Additional resources

The XML manifest file of an Office Add-in enables you to declaratively describe how your add-in should be activated when an end user installs and uses it with Office documents and applications. The offappmanifest.xsd defines an XML schema that is common to all supported Office applications (both rich client applications and their corresponding web app web clients).

Note Note

Your Office Add-in must use manifest schema version 1.1. For information about how to update your add-in to use manifest 1.1, see Update the version of your JavaScript API for Office and manifest schema files or Update the manifest of a mail add-in from schema v1.0 to v1.1.

An XML manifest file based on this schema enables an Office Add-in to do the following:

  • Describe itself by providing an ID, version, description, display name, and default locale.

  • Specify the location of the HTML file that provides the UI of the Office Add-in.

  • Specify the requested default dimensions for content Office Add-ins, and requested height for mail Office Add-ins.

  • Declare permissions that the Office Add-in requires, such as reading or writing to the document.

  • Specify how they should be used and displayed, such as content (in the document), in a task pane, or contextually with a message, appointment, or meeting request item.

  • For mail Office Add-ins, define the rule or rules that specify the context in which they will be activated and interact with a message, appointment, or meeting request item.

For examples of manifest v1.1 XML files, see Sample manifest V1.1 XML files.

The following table specifies the elements that are required for the three types of Office Add-ins and the Dictionary task pane add-in.

Important note Important

For add-ins submitted to the Office Store, all add-in locations, such as the source file locations specified in the SourceLocation element, must be SSL-secured (HTTPS). For more information see, What are some common submission errors to avoid?

Table 1: Required elements by Office Add-in type

* Added in the Office Add-in Manifest Schema version 1.1.

The following sections show examples of manifest v1.1 XML files for content, task pane, mail, and dictionary Office Add-ins.

In the manifest XML files of Office Add-ins developed using Visual Studio 2013, Visual Studio 2012 and the Office Developer Tools for Visual Studio 2013, or Napa Office 365 Development Tools, Created and Published labels and associated GUIDs are auto-generated when the add-ins are created and published. The GUID identifies which development environment created or published the Office Add-in. (The Created and Published labels and GUIDs are not shown in the following sample manifests, but you will see them when you use Visual Studio or Napa.)

If you’re using Visual Studio to develop your Office Add-in, you can use the Visual Studio manifest designer to change Office Add-in manifest settings, rather than manually changing the underlying XML markup. By default, when you open an Office Add-in manifest file in Visual Studio, it opens in the manifest designer. The designer organizes the fields in the manifest, making them easier to find. Some fields have drop-down list boxes that contain valid field values, helping reduce data entry errors.

Sample content Office Add-in manifest v1.1

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp 
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:type="ContentApp">
  <Id>01eac144-e55a-45a7-b6e3-f1cc60ab0126</Id>
  <AlternateId>en-US\WA123456789</AlternateId>
  <Version>1.0.0.0</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Sample content add-in" />
  <Description DefaultValue="Describe the features of this app." />
  <IconUrl DefaultValue="https://contoso.com/ENUSIcon.png" />
  <Hosts>
    <Host Name="Workbook" />
    <Host Name="Database" />
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="TableBindings" />
    </Sets>
  </Requirements>  
  <DefaultSettings>
    <SourceLocation DefaultValue="https://contoso.com/apps/content.html" />
    <RequestedWidth>400</RequestedWidth> 
    <RequestedHeight>400</RequestedHeight>
  </DefaultSettings>
  <Permissions>Restricted</Permissions>
  <AllowSnapshot>true</AllowSnapshot>
</OfficeApp>

Sample task pane Office Add-in manifest v1.1

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns=
  "http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:type="TaskPaneApp">
  <Id>412ce350-4161-4ad0-a5f5-0ec9d2cd3570</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Sample task pane add-in">
    <Override Locale="en-US" Value="Project add-in"/> 
  </DisplayName>
  <Description DefaultValue="Describe the features of this app.">
    <Override Locale="en-US" Value="Adds project management information to documents"/>
  </Description>
  <IconUrl DefaultValue="https://contoso.com.sa/ProjectApp/Topgunas-SA.png">
    <Override Locale="en-US" Value="https://contoso.com/ProjectApp/Topgunen-US.png"/>
  </IconUrl>
  <AppDomains>
    <AppDomain>http://www.projectlogin.com</AppDomain>
    <AppDomain>http://m.projectlogin.com</AppDomain>
    <AppDomain>http://www.projectlogin.com.sa</AppDomain>
    <AppDomain>http://m.projectlogin.com.sa</AppDomain>
  </AppDomains>
  <Hosts>
    <Host Name = "Document"/>
    <Host Name = "Workbook"/>
    <Host Name = "Presentation"/>
    <Host Name = "Project"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://contoso.com.sa/ProjectApp/ProjectAppar_SA.html">
      <Override Locale="en-US" Value="https://contoso.com/ProjectApp/ProjectAppen-US.html"/>
    </SourceLocation>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
</OfficeApp>

Sample mail Office Add-in manifest v1.1

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns=
  "http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:type="MailApp">

  <Id>971E76EF-D73E-567F-ADAE-5A76B39052CF</Id>
  <Version>1.0</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="YouTube"/>
  <Description DefaultValue=
    "Watch YouTube videos referenced in the e-mails you  
    receive without leaving your email client.">
    <Override Locale="fr-fr" Value="Visualisez les vidéos
      YouTube référencées dans vos courriers électronique
      directement depuis Outlook et Outlook Web App."/>
  </Description>
  <!-- Change the following line to specify    -->
  <!-- the web serverthat hosts the icon file. -->
  <IconUrl DefaultValue=
    "https://webserver/YouTube/YouTubeLogo.png"/>

  <Hosts>
    <Host Name="Mailbox" />
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="Mailbox" />
    </Sets>
  </Requirements>

  <FormSettings>
    <Form xsi:type="ItemRead">
      <DesktopSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_read_desktop.htm" />
        <RequestedHeight>216</RequestedHeight>
      </DesktopSettings>
      <TabletSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_read_tablet.htm" />
        <RequestedHeight>216</RequestedHeight>
      </TabletSettings>
    </Form>
    <Form xsi:type="ItemEdit">
      <DesktopSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_compose_desktop.htm" />
      </DesktopSettings>
      <TabletSettings>
        <!-- Change the following line to specify     -->
        <!-- the web server that hosts the HTML file. -->
        <SourceLocation DefaultValue=
          "https://webserver/YouTube/YouTube_compose_tablet.htm" />
      </TabletSettings>
    </Form>
  </FormSettings>

  <Permissions>ReadWriteItem</Permissions>
  <Rule xsi:type="RuleCollection" Mode="Or"> 
    <Rule xsi:type="RuleCollection" Mode="And">
      <Rule xsi:type="RuleCollection" Mode="Or">
        <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Read" />
        <Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" />
      </Rule>
      <Rule xsi:type="ItemHasRegularExpressionMatch" 
        PropertyName="BodyAsPlaintext" RegExName="VideoURL" 
        RegExValue=
        "http://(((www\.)?youtube\.com/watch\?v=)|
        (youtu\.be/))[a-zA-Z0-9_-]{11}" />
    </Rule>
    <Rule xsi:type="RuleCollection" Mode="Or">
      <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit" />
      <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit" /> 
    </Rule> 
  </Rule>
</OfficeApp>

Sample dictionary Office Add-in manifest v1.1

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp 
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:type="TaskPaneApp">
  <Id>6f28f837-8326-4231-a033-ea1d80ff9fb3</Id>
  <Version>15.0</Version>
  <ProviderName>Microsoft Office Demo Dictionary</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <!--DisplayName is the name that will appear in the user's list of applications.-->
  <DisplayName DefaultValue="Microsoft Office Demo Dictionary" />
  <!--Description is a 2-3 sentence description of this dictionary. -->
  <Description DefaultValue="The Microsoft Office Demo Dictionary is an example built to demonstrate how a publisher could create a dictionary that integrates with Office. It does not return real definitions." />
  <!--IconUrl is the URI for the icon that will appear in the user's list of applications.-->
  <IconUrl DefaultValue="https://officeimg.vo.msecnd.net/_layouts/images/general/office_logo.jpg" />
  <Hosts>
    <Host Name = "Document"/>
    <Host Name = "Workbook"/>
    <Host Name = "Presentation"/>
    <Host Name = "Project"/>
  </Hosts>
  <DefaultSettings>
    <!--Replace the value specified for DefaultValue below with the URL for your dictionary-->
    <SourceLocation DefaultValue="https://contoso.com/ExampleDictionary/DictionaryHome.html" />
  </DefaultSettings>
  <!--Permissions is the set of permissions a user will have to give your dictionary. If you need write access, such as to allow a user to replace the highlighted word with a synonym, use ReadWriteDocument. -->
  <Permissions>ReadDocument</Permissions>
  <Dictionary>
    <!--TargetDialects is the set of dialects your dictionary contains. For example, if your dictionary applies to Spanish (Mexico) and Spanish (Peru), but not Spanish (Spain), you can specify that here. This is for different dialects of the same language. Please do NOT put more than one language (e.g. Spanish and English) here. Publish separate languages as separate dictionaries. -->
    <TargetDialects>
      <TargetDialect>EN-AU</TargetDialect>
      <TargetDialect>EN-BZ</TargetDialect>
      <TargetDialect>EN-CA</TargetDialect>
      <TargetDialect>EN-029</TargetDialect>
      <TargetDialect>EN-HK</TargetDialect>
      <TargetDialect>EN-IN</TargetDialect>
      <TargetDialect>EN-ID</TargetDialect>
      <TargetDialect>EN-IE</TargetDialect>
      <TargetDialect>EN-JM</TargetDialect>
      <TargetDialect>EN-MY</TargetDialect>
      <TargetDialect>EN-NZ</TargetDialect>
      <TargetDialect>EN-PH</TargetDialect>
      <TargetDialect>EN-SG</TargetDialect>
      <TargetDialect>EN-ZA</TargetDialect>
      <TargetDialect>EN-TT</TargetDialect>
      <TargetDialect>EN-GB</TargetDialect>
      <TargetDialect>EN-US</TargetDialect>
      <TargetDialect>EN-ZW</TargetDialect>
    </TargetDialects>
    <!--QueryUri is the address of this dictionary's XML webservice (which we use to put definitions in additional contexts, such as the spelling checker.)-->
    <QueryUri DefaultValue="https://contoso.com/ExampleDictionary/WebService.asmx/Define?word="/>
    <!--Citation Text, Dictionary Name, and Dictionary Home Page will be combined to form the citation line - e.g. this would produce "Examples by: Microsoft", where "Microsoft" is a hyperlink to http://www.microsoft.com-->
    <CitationText DefaultValue="Examples by: " />
    <DictionaryName DefaultValue="Microsoft" />
    <DictionaryHomePage DefaultValue="https://www.microsoft.com" />
  </Dictionary>
</OfficeApp>

To make sure that the manifest file that describes your Office Add-in is correct and complete, validate it against the XML Schema Definition (XSD) file. You can use an XML schema validation tool or Visual Studio to validate the manifest.

For information about validating a manifest against a schema, see XML Schema (XSD) validation tool.

If you're using Visual Studio 2013, edits and additions to your add-in's manifest are automatically validated against a local copy of the Office Add-ins manifest XSD file (offappmanifest-1.1.xsd). By default, the XSD file is located in C:\Program Files (x86)\Microsoft Visual Studio 12.0\Xml\Schemas\1033.

Note Note

The offappmanifest.xsd file is obsolete. For information about updating your manifest to schema version 1.1, see Update the version of your JavaScript API for Office and manifest schema files.

By default, if your add-in tries to go to a URL in a domain other than the domain that hosts the start page (as specified in the SourceLocation element of the manifest file), that URL will open in a new browser window outside add-in pane of the Office host application. This default behavior protects the user against unexpected page navigation within the add-in pane from embedded iframe elements.

To override this behavior, specify each domain you want to open in the add-in window in the list of domains specified in the AppDomains element of the manifest file. If the add-in tries to go to a URL in a domain that isn't in the list, that URL will open in a new browser window (outside of the add-in pane).

The following XML manifest example hosts its main add-in page in the https://www.contoso.com domain as specified in the SourceLocation element. It also specifies the https://www.northwindtraders.com domain in an AppDomain element within the AppDomains element list. If the add-in navigates to a page in the www.northwindtraders.com domain, that page will open in the add-in pane.

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">
  <Id>c6890c26-5bbb-40ed-a321-37f07909a2f0</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso, Ltd</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Northwind Traders Excel" />
  <Description DefaultValue="Search Northwind Traders data from Excel"/>
  <AppDomains>
    <AppDomain>https://www.northwindtraders.com</AppDomain>
  </AppDomains>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://www.contoso.com/search_app/Default.aspx" />
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
</OfficeApp>
Show:
© 2015 Microsoft