Apps for Office XML manifest overview

apps for Office

Learn how to create or edit the manifest XML file for an app for Office.

Last modified: March 19, 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

The XML manifest file of an app for Office enables you to declaratively describe how your app 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).

An XML manifest file based on this schema enables an app for Office to do the following:

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

  • Declare which capabilities it requires, which determines which Office host applications will support the app at runtime (v1.0 only).

  • Specify the location of the HTML file that provides the user interface (UI) of the app for Office.

  • Specify the requested default dimensions for content apps for Office, and requested height for mail apps for Office.

  • Declare permissions that the app for Office 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 apps for Office, 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.

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

The following table specifies the elements that are required for the three types of apps for Office and the Dictionary task pane app.

Important note Important

For apps submitted to the Office Store, all app 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 app for Office type

* Removed in the app for Office Manifest Schema version 1.1.

** Added in the app for Office Manifest Schema version 1.1.

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

Note Note

In the manifest XML files of apps for Office 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 apps are created and published. The GUID identifies which development environment created or published the app for Office. (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" Office 365 Development Tools.)

Note Note

If you’re using Visual Studio to develop your app for Office, you can use the Visual Studio manifest designer to change app for Office manifest settings, rather than manually changing the underlying XML markup. By default, when you open an app for Office 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 app for Office 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 app" />
  <Description DefaultValue="Describe the features of this app." />
  <IconUrl DefaultValue="https://contoso.com/ENUSIcon.png" />
  <Hosts>
    <Host Name="Workbook" />
    <Host Name="Presentation" />
    <Host Name="Database" />
  </Hosts>
  <Requirements>
    <Sets DefaultMinVersion="1.1">
      <Set Name="Document" />
    </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 app for Office 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 app">
    <Override Locale="en-US" Value="Project App"/> 
  </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 app for Office 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 app for Office 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>

The following sections show examples of manifest v1.0 XML files for content, task pane, mail, and dictionary apps for Office.

Sample content app for Office manifest v1.0

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:ver="http://schemas.microsoft.com/office/appforoffice/1.0"
xsi:type="ContentApp">
  <Id>df5b5660-84ce-11e1-b0c4-0800200c9a66</Id>
  <AlternateId>en-US\WA123456789</AlternateId>
  <Version>1.0.0.0</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Sample content app" />
  <Description DefaultValue="Describe the features of this app." />
  <IconUrl DefaultValue="https://contoso.com/ENUSIcon.png" />
  <Capabilities>
     <Capability Name="Workbook" />
  </Capabilities>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://contoso.com/apps/content.html" />
    <RequestedWidth>400</RequestedWidth> 
    <RequestedHeight>400</RequestedHeight>
  </DefaultSettings>

  <Permissions>Restricted</Permissions>
  <AllowSnapshot>true</AllowSnapshot>
</OfficeApp>
NoteNote

For the IconUrl element and any child Override elements, the following image file formats are supported: BMP, GIF, EXIF, JPG, PNG and TIFF. The image specified for content apps and task pane apps must be 32 pixels by 32 pixels. The image specified for mail apps must be 64 pixels by 64 pixels.

Sample task pane app for Office manifest v1.0

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:ver="http://schemas.microsoft.com/office/appforoffice/1.0"
xsi:type="TaskPaneApp">
  <Id>ff3a1120-87ed-11e1-b0c4-0800200c9a66</Id>
  <AlternateId>en-us\WA123456789</AlternateId>
  <Version>1.0</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>ar-SA</DefaultLocale>
  <DisplayName DefaultValue="Sample task pane app">
    <Override Locale="en-US" Value="Project App"/>
  </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>
  <Capabilities>
     <Capability Name="Workbook"></Capability>
     <Capability Name="Document"></Capability>
     <Capability Name="Project"></Capability>
     <Capability Name="Presentation"></Capability>
  </Capabilities>
  <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>ReadDocument</Permissions>
</OfficeApp>

Sample mail app for Office manifest v1.0

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>FA55E9EA-52A4-4198-B23A-F106E223AB63</Id>
  <AlternateId>en-us\WA111111111</AlternateId>
  <Version>1.0.75</Version>
  <ProviderName>Microsoft</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="Lync Dialer">
    <Override Locale="en-US" Value="Lync Dialer"/>
  </DisplayName>
  <Description DefaultValue="Use this web extension to dial phone numbers using Lync." />
  <Capabilities>
    <Capability Name="Mailbox"/>
  </Capabilities>
  <DesktopSettings>
    <SourceLocation DefaultValue="https://contoso.com/dialer/dtdialer.htm" />
    <RequestedHeight>250</RequestedHeight>
  </DesktopSettings>
  <TabletSettings>
    <SourceLocation DefaultValue="https://contoso.com/dialer/tdialer.htm" />
    <RequestedHeight>150</RequestedHeight>
  </TabletSettings>
  <PhoneSettings>
    <SourceLocation DefaultValue="https://contoso.com/dialer/pdialer.htm" />
  </PhoneSettings>
  <Permissions>ReadItem</Permissions>
  <Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="reg1" RegExValue="((\(\d{3}\) ?)|(\d{3}-))?\d{3}-\d{4}" PropertyName="BodyAsPlaintext"/>
    <Rule xsi:type="ItemIs" ItemType="Message"/>
  </Rule>
  <DisableEntityHighlighting>false</DisableEntityHighlighting>
</OfficeApp>

Sample dictionary app for Office manifest v1.0

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneExtension">
  <Id>3CC9FB76-E6FE-11E1-B3D1-32CC6188709B</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" />
  <!--Capabilities is the Microsoft Office applications you will allow your dictionary to be used in. You shouldn't have to modify this area.-->
  <Capabilities>
    <Capability Name="Workbook"/>
    <Capability Name="Document"/>
    <Capability Name="Project"/>
  </Capabilities>
  <DefaultSettings>
    <!--SourceLocation is the URL for your dictionary-->
    <SourceLocation DefaultValue="https://christophernlg/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://christophernlg/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>
Show:
© 2014 Microsoft