6. Setting the start page URL
Every app has a start page whose URL
must be configured by using the <StartPage> element within the
app manifest. The SharePoint host environment uses this URL when
creating app launchers that redirect the user to the app’s start page.
When you are configuring the URL within the <StartPage> element for a SharePoint-hosted app you must use a dynamic token named ~appWebUrl, as demonstrated in the following:
~appWebUrl/Pages/Default.aspx
This use of the ~appWebUrl token
is required because the actual URL to the app’s start page will not be
known until the app has been installed. The SharePoint host environment
is able to recognize the ~appWebUrl token during app installation and it replaces it with the absolute URL to the app web.
In the case of a provider-hosted app whose start page exists within
the remote web, the <StartPage> element can be configured with
the actual URL that is used to access the start page where the remote
web has been deployed, such as in the following:
https://RemoteWebServer.wingtip.com/MyAppsRemoteWeb/Pages/Default.aspx
When you are debugging provider-hosted apps and autohosted apps, you can use a convenient dynamic token named ~remoteAppUrl
that eliminates the need to hardcode the path to the remote web during
the development phase. For example, you can configure the
<StartPage> element with the following value:
~remoteAppUrl/Pages/Default.aspx
The reason this works during debugging is due to some extra support in Visual Studio 2012. When you create a new SharePoint
app project and select the option for a provider-hosted app or an
autohosted app, Visual Studio 2012 automatically creates a second
project for the remote web that is configured as the Web Project.
Whenever you debug the Visual Studio solution containing these two
projects, Visual Studio 2012 performs a substitution to replace ~remoteAppUrl
with the current URL of the Web Project. After the substitution, the
app manifest contains a start page URL that looks like this:
https://localhost:44300/Pages/Default.aspx
The key point is that Visual Studio 2012 replaces the ~remoteAppUrl
token during a debugging session before the app manifest is installed
into the SharePoint host environment. This provides you with a
convenience in the debugging phase of a SharePoint app project.
Now, think about what happens after you have finished testing and debugging an app and its remote web. Visual Studio 2012 provides a Publish command with which you can build a final version of the AppManifest.xml file that will be distributed along with your app. In this case, what will Visual Studio 2012 do with the ~remoteAppUrl token? The answer is different depending on whether the app is an autohosted app or a provider-hosted app.
When you use the Publish command with an autohosted app, Visual Studio 2012 builds a final version of the AppManifest.xml in which the ~remoteAppUrl token remains within the <StartPage> element. This is done because the actual URL
to the remote web of an autohosted app will not be known until the app
installation process has started and the Office 365 environment has
created the remote web. You can see that the ~remoteAppUrl token is replaced by Visual Studio 2012 in some scenarios and by the Office 365 environment in other scenarios.
When you use the Publish command with a provider-hosted app, the final version of the AppManifest.xml cannot contain the ~remoteAppUrl token. You must know the URL to the remote web ahead of time. Therefore, when it is used with a provider-hosted app, the Publish command prompts you for several pieces of information including the actual URL where the remote web will be deployed.
When creating the
URL for the <StartPage> element, it is a standard practice to
include a query string that contains another dynamic token named {StandardTokens}, as demonstrated in the following example:
~remoteAppUrl/Pages/Default.aspx?{StandardTokens}
The {StandardTokens}
token is never replaced by Visual Studio 2012. Instead, this dynamic
token remains inside the final version of the app manifest that is
installed in the SharePoint host environment. The SharePoint host
environment performs a substitution on {StandardTokens} token whenever it creates the URL for an app launcher. This substitution involves replacing the {StandardTokens} token with a standard set of query string parameters that are frequently used in SharePoint app development such as the SPHostUrl parameter and the SPLangauge parameter, as shown in the following:
default.aspx?SPHostUrl=http%3A%2F%2Fwingtipserver&SPLanguage=en%2DUS
When you implement the code behind the start page of a SharePoint app, you can generally expect that the page will be passed the two query string parameters named SPLanguage and SPHostUrl,
which are used to determine the language in use and the URL that points
back to the host web. In some scenarios, the SharePoint host
environment will add additional query string parameters.
7. Understanding the app web
Each time you install a SharePoint app, you must install it on a
specific target site. A SharePoint app has the ability to add its own
files to the SharePoint host environment during installation. For
example, a SharePoint-hosted app must add a start
page and will typically add other resources, as well, such as a CSS
file and a JavaScript file to implement the app’s user experience. The
SharePoint host environment stores these files in the standard fashion
by adding them to the content database associated with the site in
which the app is being installed.
Beyond adding basic files such as a start page and a JavaScript
file, a SharePoint app also has the ability to create other
SharePoint-specific site elements in the SharePoint host during
installation such as lists and document libraries. Let’s look at an
example.
Imagine that you want to create a simple SharePoint app to manage
customers. During installation, the app can be designed to create a
customer list using the standard Contacts list type along with a set of
pages designed to provide a snazzy user experience for adding and
finding customers. Your app could additionally be designed to create a
document library upon installation so that the app can store customer
contracts as Microsoft Word documents, whereby each Word document would
reference a specific customer item in the customers list.
So, where does the SharePoint host environment store the content
added by an app during installation? The answer is inside a special
child site that the SharePoint host environment creates under the site
where the app has been installed. This child site is known as the app web.
The app web is an essential part of the SharePoint app model because
it represents the isolated storage that is owned by an installed
instance of a SharePoint app. The app web provides a scope for the
app’s private implementation details. Note that an app by default has
full permissions to read and write content within its own app web.
However, SharePoint app has no other default permissions to access
content from any other location in the SharePoint host environment. The
app web is the only place where an app can access content without
requesting permissions that then must be granted by a user.
There is a valuable aspect of the SharePoint app model that deals
with uninstalling an app and ensuring that all the app-specific storage
is deleted automatically. In particular, the SharePoint host
environment will automatically delete the app web for an app whenever
the app is uninstalled. This provides a set of cleanup semantics for
SharePoint apps that is entirely missing from the development model for
SharePoint solutions; when an app is uninstalled, it doesn’t leave a
bunch of junk behind.
Understanding the app web-hosting domain
Now, it’s time to focus on the start page for a SharePoint-hosted app. As you have seen, the start
page for a SharePoint-hosted app is added to the app web during
installation. Consider a scenario in which you have installed a
SharePoint app with the name of MyFirstApp in a SharePoint team site,
which is accessible through the following URL:
https://intranet.wingtip.com.
During app installation, the SharePoint host environment creates the
app web as a child site under the site where the app is being
installed. The SharePoint host environment creates a relative URL for
the app web based on the app’s Name property. Therefore, in this example, the app web is created with a relative path of MyFirstApp.
If the app’s start page named default.aspx is located in the app web
within the Pages folder, the relative path to the start page is
MyFirstApp/Pages/default.aspx. Your intuition might tell you that the
app’s start page will be accessible through a URL that combines the URL
of the host web together with the relative path to the app’s start
page, as in the following:
https://intranet.wingtip.com/MyFirstApp/Pages/default.aspx
However, this is not the case. The SharePoint host environment does not make the app
web or any of its pages accessible through the same domain as the host
web that is used to launch the app. Instead, the SharePoint host
environment creates a new unique domain on the fly each time it creates
a new app web as part of the app installation process. By doing so, the
SharePoint host environment can isolate all the pages from an app web
in its own private domain. The start page for a SharePoint-hosted app
is made accessible through a URL that looks like this:
https://wingtiptenant-ee060af276f95a.apps.wingtip.com/MyFirstApp/Pages/Default.aspx
At this point, it should be clear why you are required to configure the <StartPage> element for a SharePoint-hosted app by using the ~appWebUrl token.
The URL to the app web is not known until the SharePoint host
environment creates the new domain for the app web during installation.
After creating the domain for an app web, the SharePoint host
environment can replace the ~appWebUrl token with an actual URL.
Let’s examine the URL that is used to access the app web in greater
detail. Consider the following URL, which is used to access an app web
in an on-premises farm:
wingtiptenant-ee060af276f95a.apps.wingtip.com/MyFirstApp
The first part of the app web URL (wingtiptenant)
is based on the name of the tenancy where the app has been installed.
This value is configurable in an on-premises farm. In the Office 365
environment, the tenancy name is established when the customer creates
a new account, and it cannot be changed afterward.
The second part of the app web URL (ee060af276f95a) is known as an APPUID.
This is a unique 14-character identifier created by the SharePoint host
environment when the app is installed. Remember that the APPUID is
really an identifier for an installed instance of an app, as opposed to
an identifier for the app itself.
The third part of the app web URL (apps.wingtip.com) is the app web hosting domain.
You have the ability to configure this in an on-premises farm to
whatever value you would like. Just ensure that you have also
configured the proper DNS setting for this domain so that it resolves
to an IP address pointing to the web server(s) of your on-premises
farms. In Office 365 the app web-hosting domain is always
sharepoint.com.
Now, ask yourself this fundamental question: why doesn’t the SharePoint host environment serve up
pages from the app web by using the same domain as the host web from
which the app has been launched? The reasons why the SharePoint host
environment serves up pages from the app web in their own isolated
domain might not be obvious. There are two primary reasons why the
SharePoint app model does this. Both of these reasons are related to
security and the enforcement of permissions granted to an app.
The first reason for isolating an app web in its own private domain
has to do with preventing direct JavaScript calls from pages in the app
web back to the host web. This security protection of the SharePoint
app model builds on the browser’s built-in support for prohibiting
cross-site scripting (XSS). Because JavaScript code running on pages
from an app web originates from a different domain, this code cannot
directly call back to the host web. More specifically, calls from
JavaScript running on app
web pages do not run with the same established user identity as
JavaScript code-behind pages in the host web. Therefore, the JavaScript
code running on app web pages doesn’t automatically receive the same set of permissions as JavaScript code running on pages from the host web.
The second reason for creating an isolated domain for each app
web has to do with processing of JavaScript callbacks that occur on the
web server of the SharePoint host environment. Because the SharePoint
host environment creates a new unique domain for each app web, it can determine exactly which app is calling when it sees a JavaScript callback originating from a page in an app web.
The key point is that the SharePoint host environment is able to use
an internal mechanism to authenticate an app that uses JavaScript
callbacks originating from its app web. As a result, the SharePoint
host environment can enforce a security policy based on the permissions
that have been granted to the app.
Remember that a SharePoint app has a default set of
permissions by which it can access its app web but has no other
permissions by default to access any other site. The ability of the
SharePoint host environment to authenticate an app by inspecting the
URL of incoming calls originating from the app web hosting domain is
essential to enforcing this default permissions scheme.
