5. Reviewing the app manifest
Every SharePoint app requires an XML file called AppManifest.xml, which is known as the app manifest.
The app manifest contains essential metadata for the app that is read
and tracked by the SharePoint host environment when an app is
installed. Example 1 presents a simple example of what the app manifest looks like for a SharePoint-hosted app.
Example 1. An app manifest
<App xmlns=http://schemas.microsoft.com/sharepoint/2012/app/manifest
Name="MySharePointApp"
ProductID="{b93e8f64-4d14-4c72-be47-3b89f7f5fdf6}"
Version="1.0.0.0"
SharePointMinVersion="15.0.0.0" >
<Properties>
<Title>My SharePoint App</Title>
<StartPage>~appWebUrl/Pages/Default.aspx?{StandardTokens}</StartPage>
</Properties>
<AppPrincipal>
<Internal />
</AppPrincipal>
</App>
The app manifest contains a top-level <App> element which requires a set of attributes such as Name, ProductID, and Version.
Within the <App> element there is an inner <Properties>
element that contains important child elements such as <Title>
and <StartPage>. The <Title> element contains
human-readable text that is displayed to the user in the app launcher.
The <StartPage> element contains the URL that the SharePoint host
environment uses in the app launcher to redirect the user to the app’s
start page.
Example 1
shows the minimal amount of metadata required in an app manifest;
however, the app manifest for most real-world apps will contain a good
deal more. The app manifest often contains addition metadata to
configure other essential aspects of an app, such as app-level events,
authentication, permissions, and the SharePoint services that an app
requires from the SharePoint host environment. Table 1 lists the most common elements you might be required to add to an app manifest.
Table 1. The elements used in the App Manifest file
|
Element |
Purpose |
|---|
|
Name
|
Creates the URL to the app web. |
|
ProductID
|
Identifies the app. |
|
Version
|
Indicates the specific version of the app. |
|
SharePointMinVersion
|
Indicates the version of SharePoint. |
|
Properties\Title
|
Provides text for the app launcher. |
|
Properties\StartPage
|
Redirects the user to the app’s start page. |
|
Properties\SupportedLanguages
|
Indicates which languages are supported. |
|
Properties\WebTemplate
|
Supplies a custom site template for the app web. |
|
Properties\InstalledEventEndpoint
|
Executes custom code during installation. |
|
Properties\UpgradedEventEndpoint
|
Executes custom code during upgrade. |
|
Properties\UninstallingEventEndpoint
|
Executes custom code during uninstallation. |
|
AppPrincipal\Internal
|
Indicates there is no need for external authentication. This is what is always used for SharePoint-hosted apps. |
|
AppPrincipal\RemoteWebApplication
|
Indicates that the app is provider-hosted and requires external authentication. |
|
AppPrincipal\AutoDeployedWebApplication
|
Indicates that the app is autohosted and requires external authentication. |
|
AppPermissionRequests\AppPermissionRequest
|
Add permission requests that must be granted during app installation |
|
AppPrerequisites\AppPrerequisite
|
Indicates what SharePoint services must be enabled in the SharePoint host environment for the app to work properly. |
|
RemoteEndpoints\RemoteEndpoint
|
Configures allowable domains for cross-domain calls using the web proxy. |
Using the app manifest designer in Visual Studio 2012
When you are working with the app manifest in a SharePoint app
project, Visual Studio 2012 provides the visual designer shown in Figure 6. This visual designer eliminates the need to edit the XML in the AppManifest.xml file by hand. The designer provides drop-down lists that makes editing
more convenient and adds a valuable degree of validation as you are
selecting the app start page or configuring permission requests,
feature prerequisites, and capability perquisites.
Although you should take advantage of the visual designer whenever
you can to edit the app manifest, it is important to understand that it
cannot make certain types of modifications that you might require.
Therefore, you should also become accustomed to opening the AppManifest.xml file in code view and making changes to the XML within by hand. Fortunately, in times when you need to manually edit the AppManifest.xml file, Visual Studio 2012 is able to provide IntelliSense, based on the XML schema behind the app manifest.
