Introducing SharePoint Apps

Packaging and distributing apps

The final section of this chapter examines how SharePoint apps are distributed and deployed into production as well as how apps are managed over time. First, you will learn about the details of how apps are packaged into redistributable files. After that, you will see how these files are published and installed to make SharePoint apps available to users. As you will see, the SharePoint app model provides valuable support for managing apps in a production environment and upgrading to newer versions.

Packaging apps

A SharePoint app is packaged up for deployment by using a distributable file known as an app package. An app package is a file built by using the zip archive file format and it requires an extension of .app. For example, if you create a new SharePoint-hosted app project named MySharePointApp, the project will generate an app package named MySharePointApp.app as its output.

Note that the zip file format for creating an app package is based on the Open Package Convention (OPC). This is the same file format that Microsoft Office began using with the release of Office 2007 for creating Word documents (.docx) and Microsoft Excel workbooks (.xslx).

The primary requirement for an app package is that it contains the app manifest as a top-level file named AppManifest.xml. As discussed earlier in this chapter, the SharePoint host environment relies on metadata contained in the app manifest so that it can properly configure an app during the installation process.

An app package will usually contain an app icon file named AppIcon.png. The AppIcon.png file, like many of the other files in an app package, is paired with an XML file named AppIcon.png.config.xml. The purpose of this XML file is to assign the AppIcon.png file an identifying GUID.

Understanding the app web solution package

In addition to the AppManifest.xml file, the app package often contains additional files that are used as part of the app’s implementation. For example, the app package for a SharePoint-hosted app contains a file for the app’s start page along with other resources used by the start page such as a CSS file and a JavaScript file. These are examples of files that are added to the app web as part of the app installation process.

The distribution mechanism used by a SharePoint app to add pages and lists to the app web during installation is a standard solution package, which is a CAB file with a .wsp extension. If this sounds familiar, that’s because the solution package file embedded within an app package has the exact same file format as the solution package files that developers have been using to deploy SharePoint solutions in SharePoint 2007 and SharePoint 2010. The one key difference is that the solution package used by the SharePoint app model to add files to an app web is not a stand-alone file. Instead, it is embedded as a .wsp file within the app package, as shown in Figure 1-9.

When a user installs a SharePoint app, the SharePoint host environment examines the app package to see if it contains an inner solution package. It is the presence of an inner solution package within the app package file that specifies to the SharePoint host environment whether it needs to create an app web during installation. If the app package does not contain an inner solution package, the SharePoint host environment installs the app without creating an app web.

The app web solution package contains a single web-scoped feature. The SharePoint host environment activates this feature automatically on the app web immediately after the app web is created. This feature is what makes it possible to add declarative elements such as pages and lists to the app web as the app is installed.

An app web solution package cannot contain a .NET assembly DLL with server-side code. Therefore, you can say that the app web solution package embedded inside an app package is constrained because it must be a fully declarative solution package. This is different from the solution packages for farm solutions and sandboxed solutions, which can contain assembly DLLs with custom .NET code written in either C# or VB.NET.

Keep in mind that the installation of a SharePoint app doesn’t always result in the creation of an app web. Some apps are designed to create an app web during installation and some are not. A SharePoint-hosted app is the type of app that will always create an app web during installation. This is a requirement because a SharePoint-hosted app requires a start page that must be added to the app web.

However, things are different with a cloud-hosted app. Because a cloud-hosted app usually has a start page that is served up from a remote web, it does not require the creation of an app web during installation. Therefore, the use of an app web in the design of a provider-hosted app or an autohosted app is really just an available option as opposed to a requirement as it is with a SharePoint-hosted app.

When you design a provider-hosted app or an autohosted app, you have a choice of whether you want to create an app web during installation to store private app implementation details inside the SharePoint host. Some cloud-hosted apps will store all the content they need within their own external database and will not need to create an app web during installation. Other cloud-hosted apps can be designed to create an app web during installation for scenarios in which it makes sense to store content within the SharePoint host environment for each installed instance of the app.

Packaging host web features

This chapter has already discussed client web parts and UI custom actions. As you recall, these two types of features are used to extend the user interface of the host web, as opposed to many of the other types of elements in an app that are added to the app web. For this reason, the XML files containing the definitions of client web parts and UI custom actions are not deployed within a solution package embedded within the app package. Instead, the XML files that define client web parts and UI custom actions are added to the app package as top-level files.

Consider an example SharePoint app named MyAppParts that contains two client web parts. The contents of the app package for this app will contain a top-level elements.xml file for each of the client web parts and a top-level feature.xml file for the feature that hosts them. When Visual Studio 2012 creates these XML files and builds them into the output app package file, it adds a unique GUID to each file name to avoid naming conflicts, as illustrated in Figure 1-10.

The feature that hosts client web parts and UI custom actions is a web-scoped feature known as a host web feature. The SharePoint host environment is able to detect a host web feature inside an app package during app installation and activate it in the host web. When an app with a web host feature is installed at tenancy scope, that feature will be activated in more than one site.

Packaging for autohosted apps

When it comes to packaging a SharePoint app for distribution, autohosted apps are more complicated and deserve a little extra attention. The extra complexity is required because the app package for an autohosted app must contain the resources required to create an ASP.NET application on demand to deploy the remote web. An autohosted app can also be designed to create a SQL Azure database, as well, during the app installation process.

When you create a new autohosted app, Visual Studio 2012 creates two projects. There is one project for the app itself and a second web project for an ASP.NET application to implement the remote web. For example, if you create a new autohosted app using the name MyAutoHostedApp, Visual Studio 2012 creates an app project named MyAutoHostedApp and an ASP.NET project named MyAutoHostedAppWeb, and adds them to a single Visual Studio solution.

What is important to understand is that the app package built for the MyAutoHostedApp project must contain all the necessary files to deploy the ASP.NET project named MyAutoHostedAppWeb. This is a requirement because the installation of this app package must provide the Office 365 environment with the means to provision the remote web as a Windows Azure application. This is what makes it possible for an autohosted app to create its own remote web during the installation process.

Visual Studio 2012 relies on a packaging format that Microsoft created especially for the Windows Azure environment by which all the files and metadata required to deploy an ASP.NET application are built in to a single zip file for distribution. This zip file is known as a web deploy package. When used within the SharePoint app model, the web deploy package is embedded within the app package of an autohosted app for distribution.

When Visual Studio 2012 builds the web deploy package for an autohosted app, it creates the file by combining the app package name together with a web.zip extension. For example, an app packaged named MyAutohostedApp.app will have an embedded web deploy package named MyAutohostedApp.web.zip.

Now, consider the scenario in which an autohosted app has an associated SQL Azure database. The Office 365 environment must create this database on demand during app installation. Therefore, the app package must contain the resources required to create a SQL Azure database containing standard database objects, such as tables, indexes, stored procedures, and triggers.

The SharePoint app packaging model takes advantage of a second packaging format that Microsoft created for Windows Azure known as a Data Tier Application package. In this packaging format, the metadata required to automate the creation of a SQL Azure database is defined in XML files that are built in to a zip file with an extension of .dacpac. The name of the Data Tier Application package is typically based on the name of the database. For example, a SQL Azure database named MySqlDatabase will have an associated Data Tier Application package named MySqlDatabase.dacpac. If you look inside a Data Tier Application package, you can locate a file named model.xml, which defines the database objects that need to be created.

Figure 1-11 shows the layout of an app package for an autohosted app that will trigger the Office 365 environment to create a remote and a SQL Azure database as part of the app installation process. Remember that the web deploy package is required in an autohosted app package, whereas the data tier application package is optional.

When you create an autohosted app, Visual Studio 2012 automatically creates the web project and takes care of setting up all that’s required to build the web deploy package into the app package. However, you have to take a few extra steps to create a SQL database project and configure it to properly build the Data Tier Application package in to the app package.

The first step is to create a new SQL database project in Visual Studio 2012 and add it to the same solution that contains the autohosted project. Next, on the Properties page of the SQL Database project, go to the Project Settings tab and change the target platform setting to SQL Azure. This is the step that changes the project output to a Data Tier Application package. After this, you must build the SQL database project at least once to build the Data Tier Application package.

The final step is to configure the app project to reference the Data Tier Application package. You can accomplish this by using the property sheet for the autohosted app project. You will find that there is a project property named SQL Package. Once you configure the SQL Package property to point to the Data Tier Application package (.dacpac) file, you have made the necessary changes so that Visual Studio 2012 will begin building the Data Tier Application package into app package file.

Publishing apps

The app package is a distributable file that’s used to publish SharePoint apps. Once the app package has been published, it is available for users to install. In the case of SharePoint-hosted apps and autohosted apps, the app package contains all the resources required to deploy the app during the installation process. However, provider-hosted apps require the developer to deploy the remote web independently of the publication process and the installation process.

You publish a SharePoint app by uploading its app package file to one of two different places. First, you can publish an app by uploading its app package to the public Office Store. This is the right choice to make your app available to the general public, including users with SharePoint tenancies in Office 365.

The second way to publish a SharePoint app is by uploading the app package to a special type of site known as an app catalog site. This is the option to use when you want to make the app available only to users within a specific Office 365 tenancy or within a specific on-premises farm.

Publishing SharePoint apps to the Office Store

To publish an app to the public Office Store, the developer must first create a dashboard seller account. You can create this type of account by navigating to https://sellerdashboard.microsoft.com in the browser and logging on with a valid Windows Account. Once you have logged on, you can create a new dashboard seller account that is either an individual account or a company account.

A very appealing aspect of publishing apps to the Office Store with a dashboard seller account is that it provides assistance with the management of licensing as well as collecting money from customers through credit card transactions. When you create a dashboard seller account, you are able to create a second payout account from which you supply Microsoft with the necessary details so when it collects money from customers purchasing your apps, it can transfer the funds you have earned to either a bank account or a PayPal account.

Once you have gone through the process of creating a dashboard seller account, it takes a day or two for this new account to be approved. Once your account has been approved, you can then begin to publish your apps in the Office Store. The Office Store supports publishing three types of apps: you can publish SharePoint apps, Apps for Office, and Windows Azure Catalog Apps.

You publish a SharePoint app by uploading its app package file and filling in the details associated with the app. For example, the publishing process for the Office Store requires you to provide a title, version number, description, category, logo, and at least one screenshot that shows potential customers what your app looks like.

When you publish a SharePoint app, you can also indicate via the seller dashboard whether your app is free or must be purchased. If you publish an app for purchase, you can specify the licensing fee for each user or for a given number of users. There is even an option to configure a free trial period for an app that has an associated licensing fee.

Once you have uploaded an app and provided the required information, the app must then go through an approval process. The approval process involves checking the app package to ensure that it only contains valid resources. There are also checks to validate that the app meets the minimum requirements of the user experience guidelines. For example, there is a check to ensure that the start page for the app contains the required link back to the host web.

Once the app has been approved, it is then ready for use and added to the public Office Store where it can be discovered and installed by SharePoint users.

Publishing apps to an app catalog

What should you do if you want to publish an app but you don’t want to publish it to the Office Store? For example, imagine a scenario in which you don’t want to make an app available to the general public. Instead, you want to publish the app to make it available to a smaller audience such as a handful of companies that are willing to pay you for your development effort. The answer is to publish the app to an app catalog site.

An app catalog site contains a special type of document library that is used to upload and store app package files. Along with storing the app package file, this document library also tracks various types of metadata for each app. Some of this metadata is required, whereas other metadata is optional.

In the Office 365 environment, the app catalog site is automatically added when a tenancy is created for a new customer. However, this is not the case in an on-premises farm. Instead, you must explicitly create the app catalog site by using the Central Administration site or by using Windows PowerShell. Furthermore, the app catalog is created at web application scope, so you must create a separate app catalog site for each web application.

You must have farm administrator permissions within an on-premises farm to create an app catalog site. You begin by navigating to the home page of Central Administration. On the home page, there is a top-level link for Apps. When you click the Apps link, you will be redirected to a page with a group of links under the heading of App Management. Within this group of links, locate and click the link titled Manage App Catalog.

The first time you click the Manage App Catalog link, you are redirected to the Create App Catalog page, which you can use to create a new app catalog site, as shown in Figure 1-12. Note that the app catalog site must be created as a top-level site within a new site collection. On the Create App Catalog page, you can select the target web app that will host the new app catalog site.

Note that you can also use the Create App Catalog page (shown a little later in Figure 1-14) to configure user access permissions to the app catalog site. Remember that providing users with access to the app catalog site is what makes it possible for them to discover and install apps of their own. You must provide read access to users if you want them to have the ability to discover apps and install them at site scope. However, you might decide against configuring user access to the app catalog site if you plan on installing apps at tenancy scope.

Once you have created the app catalog site within an on-premises farm, you should navigate to it and inspect what’s inside. You will find that there is a document library with a title of Apps for SharePoint which is used to publish SharePoint apps. There is a second document library with a title of Apps for Office that is used to publish apps created for Office applications such as Word and Excel.

You publish a SharePoint app by uploading its app package to the Apps for SharePoint document library. The SharePoint host environment is able to automatically fill in some of the required app metadata such as the Title, Version, and Product ID by reading the app manifest as the app package is uploaded. However, there is additional metadata that must be filled in by hand or by some other means. A view of apps that have been published in the Apps for SharePoint document library is presented in Figure 1-13.

You will also notice that the app catalog site supports the management of app requests from users. The idea being that a user within a site can request an app from the Office Store. The app catalog administrator can see this request and decide whether to purchase the app or not. If the app request seems appropriate, the app catalog administrator can purchase the app and make it available for site-scope installation. Alternatively, the app catalog administrator can make the app available to the requester by using a tenancy-scoped installation.

Installing apps

Once an app has been published, it can be discovered and installed by a user who has administrator permissions in the current site. If you navigate to the Site Content page within a site and click the tile with the caption add an app, you will be redirected to the main page for installing apps named addanapp.aspx. This page displays apps that have been published to the app catalog site. Remember that an Office 365 tenancy has a single app catalog site, but on-premises farms have an app catalog site per web application. Therefore, you will not see apps that have been published to an app catalog site in a different web application.

A user requires administrator permissions within a site to install an app. If you are logged on with a user account that does not have administrator permissions within the current site, you will not be able to see apps that have been published in the app catalog site. This is true even when your user account has been granted permissions on the app catalog site itself.

Once you locate an app that you want to install, you can simply click its tile to install it. The app installation process typically prompts you to verify whether you trust the app. A page appears that displays a list of the permissions that the app is requesting along with a button to grant or deny the apps permission request. You must grant all permissions that the app has requested to continue with the installation process. There is no ability to grant one requested permission to an app while denying another; granting permissions to an app during installation is always an all-or-nothing proposition.

After the app has been installed, you will see a tile for it on the Site Content page. This tile represents the app launcher that a user can click to be redirected to the app’s start page. The app title also displays an ellipse to access a fly-out menu for app management, as illustrated in Figure 1-14.

Recall from earlier in the chapter what happens during app installation. Some apps require an app web. When this is the case, the app web is created as a child site under the current site where the app has been installed. If the app contains host feature elements such as client web parts and UI custom actions, these user interface extensions will be made available in the host site, as well.

Installing apps at tenancy scope

You have seen that the app catalog site provides a place where you can upload apps in order to publish them. Once an app has been published in the app catalog site, a user within the same Office 365 tenancy or within the same on-premises web application can discover the app and install it at site scope. However, the functionality of an app catalog site goes one step further: it plays a central role in installing apps at tenancy level.

You install an app at tenancy scope by installing it in an app catalog site. Just as with a site-scoped installation, you must first publish the app by uploading it to the Apps for SharePoint document library in the app catalog site. After publishing the app, you should be able to locate it on the Add An App page of the app catalog site and install it just as you would install an app in any other type of site. However, things are a bit different after the app has been installed in an app catalog site. More specifically, the app provides different options in the fly-out menu that is available on the Site Content page, as shown in Figure 1-15.

As you can see in Figure 1-15, an app that has been installed in an app catalog site has a Deployment menu command that is not available in any other type of site. When you click the Deployment menu command, you are redirected to a page on which you can configure the app so that you can make it available to users in other sites.

You have several options when you configure an app in an app catalog site to make it available in other sites. One option is to make the app available to all sites within the scope of the app catalog site. Or, you can be more selective and just make the app available in sites that were created by using a specific site template or sites created under a specific managed path. There is even an option to add the URLs of site collections one-by-one if you need fine-grained control.

After you configure the criteria for a tenancy-scoped app installation to indicate the sites in which it can be used, you will find that the app does not appear in those sites instantly. That’s because the SharePoint host environment relies on a timer job to push the required app metadata from the app catalog site to all the other sites. By default, this timer job is configured to run once every five minutes. During your testing you can speed things up by navigating to the Central Administration site and locating the timer job definition named App Installation Service. The page for this timer job definition provides a Run Now button that you can click to run it on demand.

Upgrading apps

The upgrade process designed by the SharePoint app model provides a much better experience compared to the upgrade process used with SharePoint solutions. When apps are published, the Office Store and app catalog sites always track their version number. When an app is installed, the SharePoint host environment sees this version number and records it for the installed app instance.

Take a simple example. Imagine you have uploaded version 1.0.0.0 of an app. After that, the app is installed in several sites via site-scoped installation. The SharePoint host environment remembers that each of these sites has installed version 1.0.0.0 of the app.

Now, imagine that you want to further develop your app. Maybe you need to fix a bug, improve its performance, or extend the app’s functionality. After you have finished your testing, you decide to update the version number to 2.0.0.0 and publish the new version in the same app catalog site where you installed the original version.

One important aspect of the upgrade process of the SharePoint app model is that an updated version of an app is never forced upon the user that installed the app. Instead, the user is notified that a new version of the app is available. This user can then decide to do nothing or to update the app to the new version. Figure 1-16 shows the notification that the SharePoint host environment adds to the app tile on the Site Contents page.

The notification depicted in Figure 1-16 contains an update link that a user can click to be redirected to a page with a button that activates the upgrade process. What actually occurs during the upgrade process is different, depending on whether the app is a SharePoint-hosted app or a cloud-hosted app.

When you are working on an updated version of a SharePoint-hosted app, you have the ability to change some of the metadata in the app manifest and to add new elements into the app web. For example, you could add a new page to the app web named startv2.aspx and then modify the app manifest to use this start page instead of the start page that was used in the original version of the app. You could also add other, new app web elements such as JavaScript files, lists, and document libraries. Many of the techniques used to upgrade elements in the app web are based on the same techniques developers have been using with feature upgrade in SharePoint solutions.

When it comes to updating a cloud-hosted app, things are different. That’s because most of the important changes to the app’s implementation are made to the remote web and not to anything inside the SharePoint host environment. If you are working with a provider-hosted app, you must roll out these changes to the remote web before you publish the new version of the app to the Office Store or any app catalog site.

It’s equally important that the updated version of the remote web must continue to support customers that will continue to use the original version of the app. Remember; there is nothing that forces the user to accept an update. You should expect that some customers will be happy with the original version and will be opposed to upgrading to a new version of an app.

Once you have pushed out more than one or more updates to a provider-hosted app, you must begin to track what version each customer is using. One technique to accomplish this task is to provide a different start page for each version of the app. Many provider-hosted apps will go a step further and store the current version of app in a customer profile that is tracked in a custom database behind the remote web.

Trapping app lifecycle events

One favorable aspect of the SharePoint app model for developers is the ability to design a cloud-hosted app with custom server-side code that is automatically executed when an app is installed, upgraded, or uninstalled. By taking advantage of the ability to add code behind these three app lifecycle events, you can program against the host web and the app web with logic to initialize, update, and cleanup site elements in the SharePoint environment. These app lifecycle events also provide the necessary triggers for updating the custom database used by provider-hosted apps and autohosted apps.

The architecture of app events is based on registering app event handlers in the app manifest that cause the SharePoint host environment to call out to a web service entry point in the remote web. Due to the architecture’s reliance on a server-side entry point, app events are not supported in SharePoint-hosted apps. Therefore, you can only use the app events in autohosted apps and provider-hosted apps.

It’s relatively simple to add support for app events to the project for an autohosted app or a provider-hosted app. The property sheet for the app project contains three properties named Handle App Installed, Handle App Uninstalling, and Handle App Upgrade, as shown in Figure 1-17.

The default value for each of these app event properties is false. The first time you change one of these properties to a value of true, Visual Studio 2012 adds a web service entry point into the web project with a name of AppEventReceiver.svc. Visual Studio 2012 also adds the required configuration information into the app manifest file, as well. If you enable all three events, the <Properties> element within <App> element of the app manifest will be updated with the following three elements:

<InstalledEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</InstalledEventEndpoint>
<UninstallingEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</UninstallingEventEndpoint>
<UpgradedEventEndpoint>~remoteAppUrl/AppEventReceiver.svc</UpgradedEventEndpoint>

After you have enabled one or more of the app events, you can then begin to write the code that will execute when the events occur. You write this code in the code-behind file named AppEventReceiver.svc.cs. If you examine this file, you will see that Visual Studio 2012 has created a class shown in the following code that implements a special interface that the SharePoint team created for remote event handling named IRemoteEventService:

public class AppEventReceiver : IRemoteEventService {
  public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties) {}
  public void ProcessOneWayEvent(RemoteEventProperties properties) { }
}

The IRemoteEventService interface is used with app events and also with other types of remote event handlers, as well. There are two methods named ProcessEvent and ProcessOneWayEvent. The SharePoint host environment makes a web service call which executes the ProcessEvent method when it needs to inspect the response returned from the remote web. The ProcessOneWayEvent method is called for cases in which the SharePoint host environment needs to trigger the execution of code in the remote web but doesn’t need to inspect the response. App events always trigger to the ProcessEvent method, so you can leave the ProcessOneWayEvent method empty in the AppEventReceiver.svc.cs file.

If you have registered for the AppInstalled event, the ProcessEvent method will execute whenever a user is installing the app. It is critical to supply robust error handling because an unhandled exception will be returned to the SharePoint host environment and cause an error in the app installation process.

When you implement the ProcessEvent method, you must return an object created from the SPRemoteEventResult class, as demonstrated in the following:

public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties) {
  // return an SPRemoteEventResult object
  SPRemoteEventResult result = new SPRemoteEventResult();
  return result;
}

The SPRemoteEventResult class was designed to make it possible for code in the remote web to relay contextual information back to the SharePoint host environment. For example, imagine that you have detected that the installer’s IP address is located in a country that you do not want to support. You can tell the SharePoint host environment to cancel the installation process and pass an appropriate error message, such as shown here:

SPRemoteEventResult result = new SPRemoteEventResult();
result.Status = SPRemoteEventServiceStatus.CancelWithError;
result.ErrorMessage = "App cannot be installed due to invalid IP address";
return result;

The ProcessEvent method passes a parameter named properties, which is based on a type named RemoteEventProperties. You can use this parameter to access important contextual information such as the URL of host web and security access token required to call back into the SharePoint host environment. Listing 1-5 shows that the properties parameter also provides an EventType property with which you can determine which of the three app events has caused the ProcessEvent method to execute.

Listing 1-5 Handling events

public SPRemoteEventResult ProcessEvent(RemoteEventProperties properties) {

  // obtain context information from RemoteEventProperties property
  string HostWeb = properties.AppEventProperties.HostWebFullUrl.AbsolutePath;
  string AccessToken = properties.AccessToken;

  // handle event type
  switch (properties.EventType) {
    case RemoteEventType.AppInstalled:
      // add code here to handle app installation
      break;
    case RemoteEventType.AppUpgraded:
      // add code here to handle app upgrade
      break;
    case RemoteEventType.AppUninstalling:
      // add code here to handle app uninstallation
      break;
    default:
      break;
  }

  // return an SPRemoteEventResult object
  SPRemoteEventResult result = new SPRemoteEventResult();
  return result;

}

Note that debugging app event handlers can be especially tricky to set up and in many situations it doesn’t work at all. That’s because the SharePoint host environment must be able to call back into the remote web. For cases in which you have installed the app into an Office 365 tenancy for testing, it is a web server in the Office 365 environment that will be issuing the call to the remote web. This web server hosted in the Office 365 environment must be able to locate and access the web server that is hosting the remote web. Therefore, attempting to debug an app event handler for which the remote web is configured to use a host name such as localhost or to use a host domain name that only resolves to the proper IP address inside your testing environment will not work.