Explore the app manifest and the package of an app for SharePoint

apps for SharePoint

Learn about the app package structure and the manifest file for an app for SharePoint.

Last modified: October 09, 2013

Applies to: apps for SharePoint | Office 365 | SharePoint Foundation 2013 | SharePoint Server 2013

In this article
App for SharePoint package structure
App for SharePoint manifest file
Additional resources

Watch the video: Package and deploy apps for SharePoint 2013

Related videos

A app for SharePoint package is a file that has an ".app" extension and that complies with the Open Packaging Conventions (OPC). The package contains the following items:

  • App manifest: This is a required file that is named appmanifest.xml. It tells SharePoint 2013 about some important properties of the app, such as its title and the permissions it needs to run. For more information about the contents of this file, see App for SharePoint manifest file.

  • SharePoint Solution Packages: Optionally, the app may include a SharePoint solution package (.wsp file) that contains the components of the app web. These components may include pages, list instances, views, documents, Web-scoped Features, and other SharePoint 2013 components. (For more information about what SharePoint components can be included in an app for SharePoint, see Types of SharePoint components that can be in an app for SharePoint.) The .wsp file may also contain apps for Office. The components in the .wsp file are deployed to the app web. For an example of an app package that includes a SharePoint solution package, see How to: Create a cloud-hosted app that includes a custom SharePoint list and content type.

  • Host web Features with Custom Actions or app parts: In addition to the SharePoint 2013 components that are deployed to the app web, an app for SharePoint can also deploy one or more custom actions (shortcut menu items or ribbon extensions) to the host web. This is accomplished by including in the app package a Feature that is not inside the package's .wsp file and that deploys the components that will go to the host web. This "loose" Feature is called a host web Feature. App parts are deployed to the host web in the same way. The host web Feature consists of a standard SharePoint 2013 feature.xml file and one or more associated elements.xml files. An elements.xml file for a custom action, for example, contains the CustomAction markup for the custom action. It can also include markup for app parts. Only these two kinds of components can be in the host web Feature. These host web Features are not itemized in the app manifest. However, they are "parts" in the OPC sense, and there is an explicit OPC relationship between the app manifest and each of these files. For an example of an app package that includes a host web Feature, see How to: Create custom actions to deploy with apps for SharePoint.

    Note Note

    Tenant administrators have the option to batch-install an app for SharePoint to multiple websites. An app that has been installed in this way is said to have Tenant scope. If the app has not been batch-installed, and is instead installed to each website separately, it has Web scope. If the host web Feature includes ribbon extensions or app parts, they are not deployed to the host webs if the app is batch-installed, so only shortcut menu items are deployed with Tenant-scoped apps. App scope should not be confused with Feature scope. Feature scope determines where the elements in a Feature are deployed. The possibilities are Farm, WebApplication, Site (that is, site collection), and Web. Only the Web option is permitted for Features in apps for SharePoint (both host web Features and Features inside a .wsp in an app package). App scope refers to the scope at which an app is installed. The possibilities are Web, in which case the app has been installed to one or more websites site-by-site, and Tenant, in which case the app has been batch installed to all or some subset of the websites in a customer's tenancy. For more information about Tenant and Web scope, see Tenancies and deployment scopes for apps for SharePoint.

  • Localization resource files (.resx): These are for localizing aspects of the app manifest that include the app title and aspects of host web Features in the app package. (Individual parts of the app package that are inside their own package, such as .wsp files, Azure Web Sites packages, and app manifests, each have their own localization processes that are applied exactly as they would be if the items in question were not part of a app for SharePoint.) For an example of an app package that includes .resx files for a host web Feature, see How to: Localize apps for SharePoint.

  • Data Tier Application Packages (DACPACs): In an autohosted app, there may be a DACPAC that installs an SQL Azure database in an account that is associated with an Microsoft SharePoint Online account.

  • Web Deploy Packages: In an autohosted app, there may be a Web Deploy package that installs a Azure Web Site that is associated with an Microsoft SharePoint Online account. For an example of an app package that includes a Web Deploy package, see How to: Create a basic autohosted app for SharePoint.

  • Apps for Office Manifests: Optionally, there may be one or more apps for Office manifests that each package an app for Office. This part can be included in the app package only if the app is going to be uploaded to a SharePoint 2013 corporate app catalog, not the public marketplace. See Publish apps for SharePoint for more information.

Every app for SharePoint includes an appmanifest.xml file. The appmanifest.xml tells SharePoint what it must know about the app and defines the app's most important properties. The following are some of the items that are specified in the manifest:

  • The internal name, product ID, and version of the app.

  • The URL of the start page, which is the page that opens when the app is started. This can be a page in the app web, a cloud-based page, or a page on a web server of the ISV.

    Note Note

    In certain circumstances, there may be restrictions on what type of file can be specified in the StartPage element. For details, see StartPage element (PropertiesDefinition complexType) (SharePoint App Manifest).

    When you are combining more than one query parameter in the StartPage value, you must use the encoded ampersand "&" rather than "&" or a semi-colon to append them together.

  • Other properties of the app. These include title and the locales supported by the app (both are required), the URLs of services that handle the post-install, post-upgrade, and pre-uninstall events, and the web template to use when the app web is created.

  • Requests for permissions the app needs to SharePoint resources outside the app web.

  • An identification, for authentication and authorization purposes, of the app principal. It is this principal that is granted permissions. This is not required for a SharePoint-hosted app.

  • A list of the prerequisites, if any, that must be available to the app in order for the app to be installed. For example, certain Features may need to be installed and activated, and certain services may need to be licensed and installed.

Note Note

The app manifest file is the only required item in the app package, but not all of the items in the previous list are required parts of the file.

For detailed information about the app manifest markup, see the node Schema reference for manifests of apps for SharePoint. This topic is not a substitute for the information in that node, including information about required elements and attributes. Also, note that SharePoint app manifests have a different schema from app for Office manifests. You can find information about the latter at Schema reference for apps for Office manifests (v1.1).

The following is an example of an appmanifest.xml file. Note that in this example, the start page for the app is an ASP.NET page that is on a remote server, not a page on the SharePoint site. The URL for the page includes a query string that passes to the remote web application the URL of the host web. The "{HostUrl}" part of the string is a token that is resolved when the app is launched. The app is requesting Write permission to all the lists in the host web. The app principal that must be granted this permission is the remote web application.

You must use either the SupportedLocales or the SupportedLanguages element in your app manifest. SupportedLanguages is being deprecated in favor of SupportedLocales. The SupportedLanguages element will continue to work even after release, but you should refrain from using it. For more information about these elements see SupportedLocales element (PropertiesDefinition complexType) (SharePoint App Manifest) and SupportedLanguages element (PropertiesDefinition complexType) (SharePoint App Manifest).

Note Note

The values of the Scope attribute of the AppPermissionRequest element are structured like URIs, but they are actually literal strings. No part of the example Scope value in the following example is a placeholder. For more information about permissions, see App permissions in SharePoint 2013.

<?xml version="1.0" encoding="utf-8" ?>
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     ProductID="{4a07f3bd-803d-45f2-a710-b9e944c3396e}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0"
     Name="MySampleApp"
>
  <Properties>
    <Title>My Sample App</Title>
    <StartPage>http://MyRemoteWebApplicationServer/default.aspx/?SPHostUrl={HostUrl}</StartPage>
    <SupportedLocales>
      <SupportedLocale CultureName="en-US" />
    </SupportedLocales>        
  </Properties>

  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="Write"/>
  </AppPermissionRequests>

  <AppPrincipal>
    <RemoteWebApplication ClientId="1ee82b34-7c1b-471b-b27e-ff272accd564" />
  </AppPrincipal>
</App>

URL tokens in the app manifest

SharePoint 2013 provides several tokens that can be used in the StartPage element and other places in apps and components of apps to represent information that is not known until the app is run. The SharePoint 2013 infrastructure resolves these tokens. Some are used at the beginning of the URL and others can be used within a URL such as the value of a query parameter. These tokens and several others can also be used in a variety of SharePoint 2013 development contexts. For detailed information about all the tokens and where they can be used, see URL strings and tokens in apps for SharePoint. For general information about other tokens and URLs in SharePoint 2013, see URLs and tokens in SharePoint 2013.

NoteNote

These tokens are not used in the Scope attribute of an AppPermissionRequest element.

Show:
© 2014 Microsoft