You have two choices for your environment to develop and test a custom SharePoint app. Your first option is a SharePoint 2013 site based on the Developer Site site template and hosted on a properly configured, on-premises SharePoint farm. (For more information about configuring an on-premises farm for deployment of apps, read the “App management configuration and deployment” section later in the chapter.) Otherwise, you can sign up for an Office 365 Developer Site subscription, which is freely available, as long as you have a valid license of Microsoft Visual Studio Premium or Ultimate with MSDN Subscription, and enables you to develop and test apps using SharePoint 2013 Online. (To create a subscription, go to http://msdn.microsoft.com/en-us/library/fp179924.aspx.)

Moreover, if you want to develop the app using Microsoft .NET and Microsoft Visual Studio 2012, you will need the Office Developer Tools for Visual Studio 2012, which can be downloaded and installed through the Web Platform Installer 4.0 tool. You also will need to install the following tools and libraries:

If you are working on a server with SharePoint 2013 installed, you need to add only Visual Studio 2012 and the Office Developer Tools for Visual Studio 2012. All the other libraries and tools are already part of the installation set of any SharePoint 2013 environment.

After you create a project, Solution Explorer presents you with a set of folders and files, as shown in Figure 8-3. The following are the main sections of this project outline:

Figure 8-3. The outline of an app for SharePoint 2013 project.

To begin playing with the current app project, just press F5 to start debugging it on the target site. First, you will notice that Visual Studio 2012 starts compiling, packaging, deploying, and installing the solution. Then your default web browser will start, showing the Default.aspx page of the current app. Figure 8-4 shows the output.

Figure 8-4. The default welcome screen of a SharePoint-hosted app.

Notice that the Default.aspx page, after a quick initialization message (“initializing…”), welcomes the current user by name. The code for retrieving the user name uses the JavaScript Client-Side Object Model (JSOM). Moreover, the page looks like every other SharePoint 2013 page, and it has a link at the top-left corner of the page for coming back to the host site.

Before clicking the Back link, notice the URL of the current page in the browser’s address bar. In the current example, which runs on-premises, the address is similar to the following:

http://apps-{UniqueID}.sp2013apps.local/sites/{ParentSiteName}/{AppName}/

Later, in the section “App management configuration and deployment,” you will learn how to configure a SharePoint web application or tenant for hosting such a URL. If you are targeting an Office 365 developer site, the URL of the app will be something like this:

https://{TenancyName}-{UniqueID}.sharepoint.com/sites/{ParentSiteName}/{AppName}/

Eventually, you will be prompted with the Office 365 logon screen to access the target host site and the app. Lastly, whether you are on-premises or in the cloud, the app URL will be enriched with a long list of query string parameters. (You’ll learn more about these later in this chapter.)

When you install your app onto the target development site, the site lists it on the Site Contents page in the Lists, Libraries, and other Apps category. As shown in Figure 8-5, the example app’s listing has a custom AppIcon.png file with the company’s logo.

Figure 8-5. The Site Contents page of a developer site with a custom app installed.

Remember, the SharePoint-hosted app uses an app website, which is a subweb of the current site collection, dedicated for hosting the app. You cannot access the app website with SharePoint Designer 2013, because support for it is disabled for this kind of website. Nevertheless, you can access it through PowerShell; simply use the Client-Side Object Model (CSOM) or any third-party tool to browse the site structure. A sample PowerShell script to retrieve information about the current app website demonstrates how to access the app website through PowerShell, by iterating through the child websites of the current site collection.

 Add-PSSnapin Microsoft.SharePoint.PowerShell -erroraction SilentlyContinue 
$site = Get-SPSite "http://devbook.sp2013.local/sites/AppsDevelopmentSite/"
Write-Host "Here are the sub-webs of the current site collection root web"
foreach ($web in $site.AllWebs) {
    Write-Host "ID: " $web.ID " - Title: " $web.Title
    if ($web.IsAppWeb -eq $true) {
        Write-Host "App Web Site Author: "$web.Author
        Write-Host "App Web Site Is App Web?" $web.IsAppWeb
        Write-Host "App Web Site Is Root Web?" $web.IsRootWeb
        Write-Host "App Web Site Is Provisioned?" $web.Provisioned
        Write-Host "App Web Site URL?" $web.Site.Url
        Write-Host "App Web Site parent Web Application:" 
        $web.Site.WebApplication
    }
}

When you execute a PowerShell script like the one in A sample PowerShell script to retrieve information about the current app website, the host console will display output similar to the following:

Here are the sub-webs of the current site collection root web
ID:  75f26332-940d-4f08-838d-cda4b6e11c62  - Title:  AppsDevelopmentSite
ID:  43d8c941-d442-490c-8ed5-4408a41d5516  - Title:  DevLeap.SP20130.ContactsApp 
App Web Site Author:  SHAREPOINTsystem
App Web Site Is App Web? True
App Web Site Is Root Web? False
App Web Site Is Provisioned? True
App Web Site URL? http://apps-3285d5aad768c4.sp2013apps.local/sites/AppsDevelopmentSite
App Web Site parent Web Application: SPWebApplication Name=DevLeap Book Portal

The most interesting information you can glean from the script output is

Now that you understand the basics of a SharePoint-hosted app, you’re ready to provision some content into the app web of your first sample app. Imagine that you want to add a list of contacts based on a custom content type. In Chapter 3 you already learned how to provision list definitions based on custom content types. Thus, this section will skip all the details, and the goal will be to create a list of contacts made of the following fields: Title, Description, Telephone, Email, and Photo.

To present the custom Contacts list to the end user, you could add a direct link to the default view of the list into the home page (Default.aspx file) of the app, but there’s an even better way. You can use the app’s Default.aspx page, which is a common SharePoint page. Open the Default.aspx file, and put some ASPX code inside the content region named PlaceHolderMain, as shown in The Default.aspx page source ASPX code changed to show the custom list of contacts. The list-relative URL used is Lists/AppContacts.

<%-- The following 4 lines are ASP.NET directives needed when using SharePoint components --%>
<%@ Page Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" MasterPageFile="~masterurl/default.master" Language="C#" %>
<%@ Register TagPrefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register TagPrefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register TagPrefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%-- The markup and script in the following Content element will be placed in the <head> of the page --%>
<asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">
    <script type="text/javascript" src="../Scripts/jquery-1.7.1.min.js"></script>
    <script type="text/javascript" src="/_layouts/15/sp.runtime.debug.js">
</script>
    <script type="text/javascript" src="/_layouts/15/sp.debug.js"></script>
    <!-- Add your CSS styles to the following file -->
    <link rel="Stylesheet" type="text/css" href="../Content/App.css" />
    <!-- Add your JavaScript to the following file -->
    <script type="text/javascript" src="../Scripts/App.js"></script>
</asp:Content>
<%-- The markup and script in the following Content element will be placed in the <body> of the page --%>
<asp:Content ContentPlaceHolderID="PlaceHolderMain" runat="server">
    <div>
        <p id="message">
            <!-- The following content will be replaced with the user name when you run the app - see App.js -->
            initializing…
        </p>
    </div>
    <WebPartPages:WebPartZone ID="spWebPartZone" runat="server">
        <WebPartPages:XsltListViewWebPart runat="server"
            ListUrl="Lists/AppContacts"
            IsIncluded="True"
            JsLink="clientTemplate.js"
            NoDefaultStyle="TRUE"
            PageType="PAGE_NORMALVIEW"
            Default="False"
            ViewContentTypeId="0x">
        </WebPartPages:XsltListViewWebPart>
    </WebPartPages:WebPartZone>

</asp:Content>

As you can see, the WebPartZone control (highlighted in bolded text) wraps a classic SharePoint XsltListViewWebPart control, which shows the items of the custom Contacts list. Figure 8-6 illustrates the resulting output in the browser after some sample contacts have been added. As you can see, the layout and the behavior of the page are the same of any other SharePoint page, because the app website is yet another SharePoint site.

Moreover, the Default.aspx page, as well as any other custom page you add to the app, is based on server controls or client-side code only. For example, you cannot add an application page (see Chapter 12 for further details) based on server-side code, because this would require a full-trust deployment of your page, which is not allowed for SharePoint-hosted apps. In case you need to create an app that uses server-side code, you should create an autohosted or a provider-hosted app.

Figure 8-6. The output of the Default.aspx page after adding an XsltListViewWebPart control for showing the custom Contacts list.

For the sake of completeness, have a look at how the JSOM interacts with your app website. Open the App.js file provided in the Scripts folder of the project. In The JavaScript code provided by default within the App.js file inside the Scripts folder of a SharePoint-hosted app project, you can see the default content of that file.

 var context;
var web;
var user;
// This code runs when the DOM is ready and creates a context object, which
// is needed to use the SharePoint object model
$(document).ready(function () {
    context = SP.ClientContext.get_current();
    web = context.get_web();
    getUserName();
});
// This function prepares, loads, and then executes a SharePoint query 
// to get the current user's information
function getUserName() {
    user = web.get_currentUser();
    context.load(user);
    context.executeQueryAsync(onGetUserNameSuccess, onGetUserNameFail);
}
// This function is executed if the above OM call is successful
// It replaces the contents of the 'helloString' element with the user name
function onGetUserNameSuccess() {
    $('#message').text('Hello ' + user.get_title());
}
// This function is executed if the above call fails
function onGetUserNameFail(sender, args) {
    alert('Failed to get user name. Error:' + args.get_message());
}

As discussed in Chapter 7 you can use the JavaScript Client Object Model (JSOM) to interact with the current site or site collection, as well with remote sites (as long as you have a set of authorized credentials). The JavaScript code provided by default within the App.js file inside the Scripts folder of a SharePoint-hosted app project uses a jQuery directive to register for the DOM document ready event. There it retrieves a reference to the current website in order to get the current user name. Because the JSOM natively provides asynchronous behavior, the code queries for the current user by invoking the executeQueryAsync method of the current context and, when successful, shows the title property of the current user in the paragraph (that is, the HTML element <p>) with an ID value of message, which is defined in the Default.aspx page. You can see that paragraph element in The Default.aspx page source ASPX code changed to show the custom list of contacts, just before the code highlighted in bold.

If you want to enrich your custom app with client-side code and the JSOM, you can simply add your custom code to this App.js file. Then you should invoke your custom functions from within the Default.aspx page or from any other custom page you will provision together with your SharePoint app. Everything you have already learned about the JSOM is valid in this context, too.

The first and main configuration tab, General, holds general information about the app, such as the title, name, and version, as well as the icon to show in the SharePoint UI. You can also choose the start page of the app, which will become the default page of the app website provisioned while installing the app. Finally, yet importantly, you can configure the query string behavior of the app. As shown in the previous section, when your app is activated, it receives a rich and long set of query string arguments. If you configure the query string property of you app, you can determine the list of arguments that the app will receive. In this property, you can use the tokens illustrated in Table 8-1. All these tokens will be resolved and appended to the URL of the default page of your app during activation.

By default, any SharePoint app uses the {StandardTokens} URL token, because it is the most complete. You can change it, however, or add your own tokens or arguments to the URL.

The Permissions section is probably the most important, and it enables you to define the permissions your app requires in order to install and execute. Whenever you install an app, the SharePoint environment will ask to the user installing it for those specific permissions. In fact, an app must be explicitly granted the required permissions in order to be installed. When installing an app, users can grant only permissions that they have, and they can grant or deny permissions with an all-or-nothing approach only. Users cannot grant a subset of the required permissions. If a user tries to install an app that requires permissions the user does not have, the SharePoint environment will raise an exception, showing a message that states the user does not have sufficient permissions to complete the action.

Every app has an identity of its own, which is associated with a security principal called the app principal. The app principal of an app has full control rights against the app web hosting the app itself. Thus, you do not need to request permissions for accessing the app web from your app. On the contrary, if your app needs to access the parent site or any external location outside the app web, you will need to request specific permissions for that.

The available permissions are defined by scope, and scopes are represented as URIs in the AppManifest.xml file. In the UI for configuring the permission, however, you see only literal names, for the sake of simplicity. Table 8-2 lists the available scopes.

Where available, the FullControl permission cannot be requested for apps that you want to publish to the Office Store. Moreover, the permission scopes related to Project Server 2013 are available only in environments where Project Server 2013 is installed.

App permissions are inherited hierarchically, and a permission applied to a parent object is implicitly applied to all of its children. For example, if you grant a Write permission at the Site Collection scope, the app will have that same permission for all of the sites within the target site collection.

Figure 8-8 shows how the Permissions tab behaves in the AppManifest.xml designer. For the sake of clarity, the AppManifest.xml file illustrated requires all the available permissions.

Figure 8-8. The Permissions tab in the designer for AppManifest.xml.

The XML source of an AppManifest.xml file with all the available permission scopes defined provides the XML source of an AppManifest.xml file configured as illustrated in Figure 8-8.

<?xml version="1.0" encoding="utf-8" ?>
<!--Created:cb85b80c-f585-40ff-8bfc-12ff4d0e34a9-->
<App xmlns="http://schemas.microsoft.com/sharepoint/2012/app/manifest"
     Name="DevLeapSP20130ContactsApp"
     ProductID="{abe98779-6d6c-490c-83d4-8bf9acd4820c}"
     Version="1.0.0.0"
     SharePointMinVersion="15.0.0.0">
  <Properties>
    <Title>DevLeap.SP20130.ContactsApp</Title>
    <StartPage>~appWebUrl/Pages/Default.aspx?{StandardTokens}</StartPage>
  </Properties>
  <AppPrincipal>
    <Internal />
  </AppPrincipal>
  <AppPermissionRequests>
    <AppPermissionRequest Scope="http://sharepoint/bcs/connection" Right="Read" />
    <AppPermissionRequest Scope="http://sharepoint/projectserver/enterpriseresources" Right="Write" />
    <AppPermissionRequest 
Scope="http://sharepoint/content/sitecollection/web/list" Right="FullControl" >
      <Property Name="BaseTemplateId" Value="101" />
    </AppPermissionRequest>
    <AppPermissionRequest Scope="http://sharepoint/social/microfeed" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/projectserver/projects" Right="Write" />
    <AppPermissionRequest Scope="http://sharepoint/projectserver" Right="Manage" />
    <AppPermissionRequest Scope="http://sharepoint/projectserver/reporting" Right="Read" />
    <AppPermissionRequest Scope="http://sharepoint/search" 
Right="QueryAsUserIgnoreAppPrincipal" />
    <AppPermissionRequest 
Scope="http://sharepoint/projectserver/projects/project" Right="Write" />
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/social/core" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/projectserver/statusing" Right="SubmitStatus" />
    <AppPermissionRequest Scope="http://sharepoint/taxonomy" Right="Write" />
    <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="FullControl" />
    <AppPermissionRequest Scope="http://sharepoint/projectserver/workflow" Right="Elevate" />
  </AppPermissionRequests>
</App>

Notice the List permission, highlighted in bold, with the optional property BaseTemplateId configured to a value of 101 (for “document library”). When you install an app with some custom permissions requests, the SharePoint environment will ask you to trust it. Figure 8-9 illustrates how the request to trust the app is prompted to an end user. As you can see, the form asks the end user to choose the library to which you would like the app to have access. If you trust the app and give it the requested permissions, then you will be able to use it.

Figure 8-9. The page for trusting an app during installation.

In case you later decide to change or retract permissions from an app, you can remove the whole app, or you can go to the permissions-management page specific for that app. To view that page, go to the Site Contents page, click the ellipsis just behind the app icon, and select the Permissions link on the ECB menu. This link will lead you to the permissions-management page that is illustrated in Figure 8-10.

Figure 8-10. The permissions-management page for an app.

The third configuration tab of the AppManifest.xml file, Prerequisites, provides a grid for configuring the list of the prerequisites that must be installed on the SharePoint site in order for the app to be installed. If necessary, you can configure the following prerequisites:

Each prerequisite feature or service can also specify a minimum version requirement. Figure 8-11 shows the outline of this configuration tab, with all of the out-of-the-box prerequisites configured.

Figure 8-11. The outline of the tab for configuring app prerequisites.

The resulting configuration defines an AppPrerequisites element in the AppManifest.xml file, filled with a set of elements with name AppPrerequisite. Each AppPrerequisite element is configured with a Type attribute, an ID attribute, and an optional MinimumVersion attribute. Here is the XML definition of the AppPrerequisite element for the Visio Services capability:

<AppPrerequisite Type="Capability" ID="778D6B91-D46F-40E6-B7A4-1C666B800D03" MinimumVersion="15.0.0.0" />

As you can see, the prerequisite is referenced by ID, which in general is a globally unique identifier (GUID). The Type attribute can assume values of Feature, Capability, or AutoProvisioning. The first two values are self-explanatory; the AutoProvisioning value is suitable only for autohosted apps. In fact, for autohosted apps, you can automatically provision components that the app needs while provisioning the app itself. In this case, the ID attribute can assume literal values (instead of GUIDs) corresponding to RemoteWebHost and Database, for provisioning a Windows Azure website and a SQL Azure database, respectively. The MinimumVersion attribute is in the form of a product version: {number} ({major version}.{minor version}.{build number}.{revision}).

For services such as Excel, Access, or Visio Services, the infrastructure will verify that the service is installed and licensed. For features at the Farm, WebApplication, or Site scope, the infrastructure will verify that they are deployed and activated. For features that can be activated at the Web scope on the target app web, the environment will automatically activate them during app installation.

Through the Supported Locales tab, you can configure the locales supported by your app, together with the resource files corresponding to each locale. Every SharePoint app can support one or more locales, providing dedicated resources and resource files. On this tab, you simply need to configure a locale ID (using the culture name) and the name and content of the corresponding resource file. Each time you configure a supported locale, Visual Studio 2012 creates the corresponding .resx file for you. Figure 8-12 shows the tab configured for supporting the Italian locale and the French locale. It also shows the SharePoint app project outline, with the .resx files corresponding to these supported locales.

Figure 8-12. The tab for configuring the supported locales for an app.

The last tab of the AppManifest.xml configuration panel is Remote Endpoints. A remote endpoint is a URL that your app will use for accessing data or services from external domains. Nowadays, there are cross-site scripting (XSS) policies denying access to external domains via JavaScript code. When you are developing an HTML-and-JavaScript-based SharePoint app, use this tab to configure the list of allowed remote endpoints. SharePoint will then provide a JavaScript-based API (SP.RequestExecutor) that will call the configured remote endpoints for you, and pass back the data it receives. Figure 8-13 shows how the configuration for remote endpoints behaves in Visual Studio 2012.

Figure 8-13. The tab for configuring the remote endpoints for an app.

Configuring the remote endpoints on this tab results in the creation of an XML section within the AppManifest.xml file, such as the following:

<RemoteEndpoints>
    <RemoteEndpoint Url="http://www.myremoteservice.com" />
</RemoteEndpoints>

In Chapter 9, you will learn how the SP.RequestExecutor API works and how to take advantage of it in your apps.

To recap, an App Part (also known as a Client Part) renders some content of the app in an IFrame inside pages of the parent site. Now, imagine that you want to extend the functionalities of the SharePoint app you developed during the previous sections. For example, you could add an App Part for searching the contacts from within the parent SharePoint site. Figure 8-14 shows the intended output result.

Figure 8-14. The sample App Part in action while searching app contacts.

To add a new App Part, simply right-click the app project while in Visual Studio and select Add | New Item | Client Web Part (Host Web) from the list of available item templates. Then provide a name for the target App Part. For this example, call it SearchContactsAppPart. When you add an App Part to a project, a wizard will prompt you to enter some information about the App Part, as shown in Figure 8-15. In this wizard, you can choose between creating a new App Part and using an already existing ASPX page, which will be loaded inside the IFrame that will host the App Part. Click the Finish button to create an ASPX page file and a new feature element for provisioning your App Part.

Figure 8-15. The UI for adding an App Part to a target project.

The ASPX page file is just another web page that will be hosted in your app web, and that will have the same capabilities of the Default.aspx page or any other custom ASPX page. Here you can use the JSOM to interact with SharePoint and with your app web. The default content of the SearchContactsAppPart.aspx page behind the custom App Part shows the default content of the SearchContactsAppPart.aspx file created by Visual Studio 2012 upon creation of the App Part.

<%@ Page language="C#" Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage, Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages" Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<WebPartPages:AllowFraming ID="AllowFraming" runat="server" />
<html>
<head>
    <title></title>
    <script type="text/javascript">
        // Set the style of the client web part page 
        // to be consistent with the host web.
        function setStyleSheet() {
            var hostUrl = ""
            if (document.URL.indexOf("?") != -1) {
                var params = document.URL.split("?")[1].split("&");
                for (var i = 0; i < params.length; i++) {
                    p = decodeURIComponent(params[i]);
                    if (/^SPHostUrl=/i.test(p)) {
                        hostUrl = p.split("=")[1];
                        document.write("<link rel="stylesheet" href="" +
                        hostUrl + "/_layouts/15/defaultcss.ashx" />");
                        break;
                    }
                }
            }
            if (hostUrl == "") {
                document.write("<link 
rel="stylesheet" href="/_layouts/15/1033/styles/themable/corev15.css" />");
            }
        }
        setStyleSheet();
    </script>
</head>
<body>
</body>
</html></title>

As you can see, the page references the classic SharePoint server-side libraries and controls, and inherits its behavior from the Microsoft.SharePoint.WebPartPages.WebPartPage base class, without defining any master page file. Moreover, the server-side control called AllowFraming enables your page to be rendered inside an IFrame.

Just after the server control for allowing the frame support is HTML and JavaScript code for rendering the basic elements of the page, together with default theming consistent with the host SharePoint website. By default, the page will try to locate the SPHostUrl parameter in the query string and will download the CSS style (if it exists) from the URL _layouts/15/defaultcss.ashx relative to the SPHostUrl. If the SPHostUrl argument is missing, the App Part will be rendered using the CoreV15.css style of the current app website.

To implement the App Part, you will have to add some HTML and JavaScript code to the page. For the current sample, you will reuse some ideas and code already shown in Chapter 7. For example, you’ll add a text box and a button for searching contacts. Inside the body element of the page, add the following markup:

Search Contacts: <input type="text" name="textToSearch" id="textToSearch" />
  <input type="button" value="Search" onclick="javascript:searchContacts();" />
  <br /> <br />
  <div id="searchOutput" style="overflow:auto; height: 130px;"></div>

Then, just before the closing tag of the head element of the page, add the following references to scripts:

<script type="text/javascript"
  src="http://ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>
  <script type="text/javascript"
  src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.8.3.min.js"></script>
  <script type="text/javascript"
  src="http://code.jquery.com/ui/1.9.2/jquery-ui.min.js"></script>
  <script type="text/javascript"
  src="/_layouts/15/sp.runtime.debug.js"></script>
  <script type="text/javascript" src="/_layouts/15/sp.debug.js"></script>
  <script type="text/javascript"
  src="../Scripts/SearchContacts.js"></script>

Now you will need to add a new JavaScript file in the Scripts folder of the project. For example, give it a name of SearchContacts.js. The JavaScript code behind the App Part defined in the SearchContactsAppPart.aspx page shows how the code should look.

var clientContext;
var web;
var contactsList;
var listItems;
// This code runs when the DOM is ready and creates a context object which is 
// needed to use the SharePoint object model
$(document).ready(function () {
    clientContext = SP.ClientContext.get_current();
    web = clientContext.get_web();
});
// This function prepares, loads, and then executes a SharePoint
// query to get the search query for app contacts results
function searchContacts() {
    contactsList = web.get_lists().getByTitle("App Contacts");
    var textToSearch = $("#textToSearch").val();
    var camlQuery = new SP.CamlQuery();
    var q = '<View><Query><Where><Contains><FieldRef ' +
      'Name="DevLeapAppContactDescription" /><Value Type="Text">' + 
      textToSearch + '</Value></Contains></Where></Query></View>';
    camlQuery.set_viewXml(q);
    listItems = contactsList.getItems(camlQuery);
    clientContext.load(listItems);
    clientContext.executeQueryAsync(onSearchQuerySucceeded, onSearchQueryFailed);
}
// Output the result
function onSearchQuerySucceeded(sender, args) {
    $("#searchOutput").empty();
    if (listItems.get_count() > 0) {
        var listItemsEnumerator = listItems.getEnumerator();
        // Iterate though all of the items         while (listItemsEnumerator.moveNext()) {
            var item = listItemsEnumerator.get_current();
            var id = item.get_id();
            var contactDescription = item.get_item(
            "DevLeapAppContactDescription");
            var contactTelephone = item.get_item("DevLeapAppContactTelephone");
            var contactEmail = item.get_item("DevLeapAppContactEmail");
            var contactPhoto = item.get_item("DevLeapAppContactPhoto").get_url();
            $("#searchOutput").append('<a href="mailto:' + contactEmail + '">' +
                '<img style="float: left; margin: 5px;" src="' +
                contactPhoto + '" align="left" alt="' + contactDescription + 
                '"/></a>'),
        }
    }
    else {
        $("#searchOutput").append('<div>No results matching the query. ' +
          'Try again …</div>'),
    }
}
function onSearchQueryFailed(sender, args) {
    alert('Request failed ' + args.get_message() + '
' + args.get_stackTrace());
}

As you can see, the code is made of standard JSOM directives for searching the target list of contacts using Collaborative Application Markup Language (CAML).

The last piece of code to evaluate is the feature element for provisioning the App Part. In fact, when you add an App Part to a SharePoint app project, Visual Studio 2012 adds also a feature element to the project. In The feature element file for provisioning the sample SearchContactsAppPart shows the one related to the sample App Part illustrated in this section.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <ClientWebPart Name="SearchContactsAppPart" Title="SearchContactsAppPart Title" 
                 Description="SearchContactsAppPart Description" 
                 DefaultWidth="600"
                 DefaultHeight="200">
<!-- Content element identifies the location of the page that will render inside the client web part
Properties are referenced on the query string using the pattern _propertyName_
Example: Src="~appWebUrl/Pages/ClientWebPart1.aspx?Property1=_property1_" -->
    <Content Type="html" Src="~appWebUrl/Pages/SearchContactsAppPart.aspx" />
    <!-- Define properties in the Properties element.
         Remember to put Property Name on the Src attribute of the 
         Content element above. -->
    <Properties>
    </Properties>
  </ClientWebPart>
</Elements>

The ClientWebPart element provisions an App Part, providing descriptive information like Name, Title, Description, DefaultWidth, and DefaultHeight. If you are creating a multilingual app, you should at least provide a resource-based value for both the Title and Description attributes, using the classic $Resources:ResourceName; syntax and providing a value for the key ResourceName in every RESX file.

In addition, you can include a list of custom properties, defined through a set of Property elements (children of the Properties element). Every Property element can assume the structure illustrated in Property element structure and define a property that will be configurable through the SharePoint UI while managing the page hosting the App Part. You can also define properties that are not configurable by the end users, but that are still needed by the App Part internal logic.

<Property xmlns="http://schemas.microsoft.com/sharepoint/"
    Name="Text"
    DefaultValue="Text"
    Multilingual= "true" | "false"
    PersonalizationScope="user" | "shared"
    PersonalizableIsSensitive= "true" | "false"
    Type= "string" | "int" | "boolean" | "enum"
    RequiresDesignerPermission= "true" | "false"
    WebBrowsable= "true" | "false"
    WebCategory="Text"
    WebDescription="Text"
    WebDisplayName="Text"
    ManagedLinkConvertServerLinksToRelative= "true" | "false"
    ManagedLinkFixup= "true" | "false" >
    <EnumItems>
        <EnumItem 
            Value="Text"
            WebDisplayName="Text" />
    </EnumItems>
</Property>

The most interesting things to notice are the available data types, which are string, int, Boolean, and enum (shown in Figure 8-15). In case of the enum type, you will have to provide the admitted values using the EnumItems child element. Some other interesting attributes are PersonalizationScope, for defining whether the property can be personalized by each user or will assume a shared value; and RequiresDesignerPermission, for determining whether the user has to have designer permissions to edit the property value. Moreover, you can define attributes to configure the appearance of every single property in the UI, including WebBrowsable, WebCategory, WebDescription, and WebDisplayName. These last attributes have names and meanings that correspond to similar properties of SharePoint Web Parts, which will be discussed in Chapter 11 A sample Property element defining a property of type enum, defined for the sample App Part for searching contacts demonstrates how to define an enum property for defining the orientation (horizontal or vertical) of results for the sample App Part for searching contacts.

<Property Name="FlowDirection"
          DefaultValue="Horizontal"
          Multilingual="true"
          PersonalizationScope="shared"
          PersonalizableIsSensitive="true"
          Type="enum"
          RequiresDesignerPermission="true"
          WebBrowsable="true"
          WebCategory="Custom Properties"
          WebDescription="Flow Direction"
          WebDisplayName="Flow Direction"
          ManagedLinkConvertServerLinksToRelative="true"
          ManagedLinkFixup="true">
  <EnumItems>
    <EnumItem Value="Horizontal" WebDisplayName="Horizontal"/>
    <EnumItem Value="Vertical" WebDisplayName="Vertical"/>
  </EnumItems>
</Property>

The selected values of configurable properties can be passed via query string to the ASPX page behind the App Part. The syntax for passing the properties is to append them to the Src attribute value at the end of the App Part page URL. The name for the query string arguments can be anything you like, while the value has to be represented as _{PropertyName}_. For example, to get the value of a property with the name FlowDirection into an argument with the name Direction, you should write the Src attribute value as follows:

Src="~appWebUrl/Pages/ClientWebPart1.aspx?Direction=_FlowDirection_"

Remember that the feature element is an XML file, so any special characters, such as & or %, should be represented in URL-encoded format. To access the provided values while executing the App Part, use jQuery extensions or custom JavaScript code, just as you would with any other HTML or JavaScript application.

Figure 8-16 shows how the various types of properties are rendered in the SharePoint UI. To display the tool pane, click the Edit Web Part menu, which is available while the page is in Edit mode, as it is for any other classic Web Part in SharePoint.

Figure 8-16. The UI for configuring the properties of an App Part.

After you install your app, you can add the App Part to a target page. You simply need to edit the page, and on the ribbon’s Insert tab, click the App Part button. You will be prompted with the list of all the available App Parts, including SearchContactsAppPart. Figure 8-17 illustrates the UI for inserting the sample App Part in a target page.

Figure 8-17. The UI for adding an App Part to a target page.

Notice that, although you are still in edit mode, your App Part is fully functional already. In fact, the code behind the App Part is based on JavaScript and runs both in edit and design mode.

Custom UI extensions allow your SharePoint apps to interact with the end user through the standard UI of SharePoint. You can add custom menu items in the ECB, and custom ribbon commands and tabs to the ribbons of standard SharePoint pages, while using exactly the same tools and techniques you would for any other UI customization (see Chapter 12). In addition, while working in SharePoint apps, you also have the support of a few dedicated tools and wizards.

To create a custom UI extension, you simply need to add a new item to an already existing SharePoint app project. To add a new menu item, right-click the project in Visual Studio 2012 Solution Explorer, select Add from the menu, and then choose New Item and finally Menu Item Custom Action. In the wizard that appears, provide the appropriate answers to create the new menu item. Figure 8-18 depicts the first step of this wizard.

Figure 8-18. The first step of the wizard for creating a new menu item extension.

First, you can choose whether the menu item will be created within the app web or the host web. Then you can choose where the menu item will be scoped. The available options are

The wizard will adapt to the selection you make. For example, if you choose List Instance, then you will have to choose the specific target instance; when choosing Content Type, you will have to select the target content type; and so on.

In the second step of the wizard (Figure 8-19), you define the caption of the menu item, as well as the target URL to drive the user to when the menu item is selected.

Figure 8-19. The second step of the wizard for creating a new menu item extension.

After you complete the wizard, Visual Studio will prompt you with a new feature element that defines the custom action. A sample feature element for provisioning a menu item extension shows sample content for such a file.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="db823841-8f6c-4b9a-912d-2b839eeddb43.SendDocumentToContact"
                RegistrationType="List"
                RegistrationId="101"
                Location="EditControlBlock"
                Sequence="10001"
                Title="Send document to the Contacts App">
    <!-- 
    Update the Url below to the page you want the custom action to use.
    Start the URL with the token ~remoteAppUrl if the page is in the
    associated web project, use ~appWebUrl if page is in the app project.
    -->
    <UrlAction Url="~appWebUrl/Pages/SendDocument.aspx" />
  </CustomAction>
</Elements>

The UrlAction element, within the CustomAction element, defines a new menu item that targets the ECB menu of any item within a document library, as declared by attributes RegistrationType = List and RegistrationId = 101. For further details about the various options for the attributes of CustomAction and UrlAction elements, please read Chapter 12. Notice also the Id attribute of the CustomAction element, which defines the unique ID of the menu item and should be a unique literal value. Moreover, the Url attribute defined in the UrlAction element can reference content under the app web, in case you start the URL with the ~appWebUrl token. Otherwise, if the target content is under the host web, you can start the URL with the ~remoteAppUrl token.

The next steps are to create a page with a name corresponding to the one you provided while defining the custom action, and to start debugging the app. To create a new page, right-click the Pages folder in the SharePoint app project and select Add | New Item | Page. Moving into a document library within the host web, you will notice that the ECB menu contains the new item Send Document To The Contacts App (see Figure 8-20). Click this menu item and you will be redirected to the custom page you just created.

Figure 8-20. The custom menu item extension in action.

Behind the scenes, the SharePoint environment invokes a GET method to redirect the browser to a URL such as the following:

_layouts/15/appredirect.aspx?client_id={clientId}&redirect_uri=%7EappWebUrl%2FPages%2FSendDocument%2Easpx

where the {clientId} argument is a token describing the current context. If you want to provide some arguments to the target URL—for example, the ID of the source document or the ListId of the source library—you can modify the Url attribute of the UrlAction element, including some predefined tokens. Here is a sample Url value for this purpose:

<UrlAction Url="~appWebUrl/Pages/SendDocument.aspx?ItemId={ItemId}&ListId={ListId}" />

All the available URL tokens will be discussed in the “Custom actions” section of Chapter 12.

Many menu item customizations apply to custom ribbons, as well. To add a custom ribbon, for example, right-click the SharePoint app project and select Add | New Item | Ribbon Custom Action. A wizard will ask you questions very similar to those for creating a new menu item. This time, however, you can choose from only three scope values: List Template, List Instance, and None. While the first two scopes are the same as before, while creating custom menu items, the None option creates a ribbon command independent from any target scope.

The second step of the wizard (Figure 8-21) is specific for ribbons and asks you to provide information about the location of the ribbon command, the caption, and the target URL. The location of the ribbon can be one of the predefined locations (see Chapter 12) or a custom location.

Figure 8-21. The second step of the wizard for creating a new ribbon command extension.

Once again, the result of the wizard will be an XML file defining a feature element of type CustomAction. This time, the CustomAction will use the syntax to define a ribbon command. (For more details about defining ribbon commands, ribbon tabs, and groups, read Chapter 12.) An interesting thing to notice is that with a ribbon command, you can either define a target URL to redirect the end user to, or you can provide a JavaScript set of instructions to execute directly in the context of the current page. A sample feature element for provisioning a menu item extension shows the resulting XML feature element, while Figure 8-22 illustrates the resulting ribbon command.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="56116170-9f53-4000-ba3e-5eafe9c43ec3.Sent"
                RegistrationType="List"
                RegistrationId="101"
                Location="CommandUI.Ribbon"
                Sequence="10001"
                Title="Invoke 'SendDocumentsToContact' action">
    <CommandUIExtension>
      <!-- 
      Update the UI definitions below with the controls and the command actions
      that you want to enable for the custom action.
      -->
      <CommandUIDefinitions>
        <CommandUIDefinition 
        Location="Ribbon.Documents.Manage.Controls._children">
          <Button Id="Ribbon.Documents.Manage.SendDocumentsToContactButton"
                  Alt="Send Documents to Contact"
                  Sequence="100"
                  Command="Invoke_SendDocumentsToContactButtonRequest"
                  LabelText="Send Documents to Contact"
                  TemplateAlias="o1"
                  Image32by32="_layouts/15/images/placeholder32x32.png"
                  Image16by16="_layouts/15/images/placeholder16x16.png" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
      <CommandUIHandlers>
        <CommandUIHandler Command="Invoke_SendDocumentsToContactButtonRequest"
                          CommandAction="~appWebUrl/Pages/Default.aspx"/>
      </CommandUIHandlers>
    </CommandUIExtension >
  </CustomAction>
</Elements>

Figure 8-22. The custom ribbon command extension created in the sample.

From a practical viewpoint, an autohosted app can do almost everything a SharePoint-hosted app can do. However, by default, an autohosted app does not have an app web for storing data and information; instead, it uses a persistence infrastructure of its own, which can be based on SQL Azure. The autohosted model works only for SharePoint sites hosted on Office 365 or SharePoint Online. At the time of this writing, Microsoft has not yet announced the pricing model for hosting apps on Windows Azure websites. In fact, so far, apps hosted on Windows Azure cannot be published to the Office Store.

To create an autohosted app, you can start Visual Studio 2012 and create a new SharePoint app. In the first step of the resulting wizard, provide the URL of an Office 365–hosted site and choose the autohosted hosting model. The procedure may be similar, but the solution outline (see Figure 8-23) is slightly different compared to a SharePoint-hosted app.

Figure 8-23. The solution outline for an autohosted app for SharePoint.

The outline includes a classic ASP.NET web application, which can be any kind of ASP.NET web application, as well as a SharePoint app project, which contains only the AppIcon.png and AppManifest.xml files. These two files are the same as those of a SharePoint-hosted app. You could add to the SharePoint app project feature elements for provisioning content types, pages, lists, and so on; however, these elements would require an app website. On the contrary, because you are developing an autohosted app, you will probably prefer to benefit from the Windows Azure environment instead of using SharePoint for storing data and content of your app.

The ASP.NET web application is made of a Pages folder with a Default.aspx page, a Scripts folder with some useful JavaScript files, the classic web.config file, and a TokenHelper.cs file, which supports the application in managing and handling the secure communication with SharePoint. The Default.aspx file, unlike the SharePoint-hosted app page, will have some .NET code behind it. If you open the Default.aspx.cs file, you will find code similar to The .NET code behind the Default.aspx page of an autohosted app.

 using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
namespace DevLeap.SP2013.ContactsAppAutoHostedWeb.Pages {
    public partial class Default : System.Web.UI.Page {
        protected void Page_Load(object sender, EventArgs e) {
            // The following code gets the client context and 
            // Title property by using TokenHelper.
            // To access other properties, you may need to request
            // permissions on the host web.
            var contextToken = TokenHelper.GetContextTokenFromRequest(
            Page.Request);
            var hostWeb = Page.Request["SPHostUrl"];
            using (var clientContext =
              TokenHelper.GetClientContextWithContextToken(
              hostWeb, contextToken, Request.Url.Authority)) {
                clientContext.Load(clientContext.Web, web => web.Title);
                clientContext.ExecuteQuery();
                Response.Write(clientContext.Web.Title);
            }
        }
    }
}

The main part of the code is the Page_Load method, where the page retrieves the Title property of the host web and writes it back to the HTTP response. Because the autohosted app site is hosted outside SharePoint, the code needs to retrieve a security context token with proper authorizations to access the host web and its properties. The following line does the magic:

var contextToken = TokenHelper.GetContextTokenFromRequest(Page.Request);

It uses the TokenHelper class, which is automatically generated by the project template, and that class reads a few arguments from the query string to create a secured communication session against the host web. The code of the TokenHelper class is open, you can read it and eventually change it. Of course, just because you can it does not mean you should change it. Probably the best thing to do is to read through the TokenHelper class—without changing it—to better understand how it works with the CSOM. You can see that the page uses the CSOM to retrieve the Title of the host web and creates a ClientContext object instance based on the contextToken gained through the page request. You can replace this code with anything else, and if you like to interact with the host web, you can simply use the CSOM to provide an authenticated and authorized context token to the ClientContext. (For more thorough detail on the CSOM, see Chapter 7.)

If you start debugging the app, you will have to provide credentials to access the Office 365 environment before you are presented with the page for trusting the app. Because an autohosted app works outside the context of SharePoint, you will always have to trust it during installation. Next, you will be redirected to the site hosting the app. Notice that while debugging in your development environment, the autohosted app site will run locally on Internet Information Services (IIS) Express so that you can debug it on your local machine. In the next section, you will learn how to publish the app, once you have finished development and testing.

As you can see from the output of the app in the web browser, you can control all the UI and UX details for an autohosted app. Thus, the layout of the output is up to you and your code.

Starting from scratch is one way to create your SharePoint App, but luckily for ASP.NET developers, there is another way: you can convert a classic ASP.NET project into a SharePoint autohosted app, meaning you can take advantage of the new and more productive MVC4 (Model-View-Controller 4.0) pattern available in ASP.NET 4.x. To try this option, create a new solution made of an ASP.NET 4.0 site based on MVC4, or use an already existing site you want to convert to a SharePoint app. Right-click the web project node in Solution Explorer and select the Add App For SharePoint Project menu item (Figure 8-24). Of course, you can use this functionality against any kind of ASP.NET project, not only with MVC4 sites.

Figure 8-24. The menu item for creating a SharePoint app from an already existing ASP.NET website.

Next, provide the URL of the host web, on Office 365 or SharePoint Online, for publishing the already existing ASP.NET website. Once you do, a new SharePoint app project will be added to the solution and some new references will be added to the ASP.NET web project. The name of the SharePoint app project will be the same of the ASP.NET web project, ending with the .SharePoint suffix. Moreover, the action will add a TokenHelper class to the ASP.NET web project, in order to support the SharePoint 2013 authentication and authorization environment. Now, the ASP.NET web project is the UI for the SharePoint app project. In fact, if you open the property grid of the SharePoint app, you can see that the MVC4 project is configured in the Web Project property of the app. See Figure 8-25 for details.

Figure 8-25. The property grid of the SharePoint autohosted app with the Web Project property in evidence.

As you can see from Figure 8-25, there are also properties for configuring a SQL Database project and a SQL Data script. Suppose the example autohosted app uses a custom SQL Azure database on the back end for storing contacts data. In this case, you can add a new SQL Server database to the current solution. To do so, right-click the solution and choose Add | New Project | SQL Server Database Project. Open the properties of the database project and configure its target platform to SQL Azure.

Now add a new table for holding contacts to the database project (Add | New Item | Table) and configure some fields. For the sake of simplicity, in addition to the Id primary key field, configure just the following text fields: ContactDescription, ContactPhone, and ContactEmail. The final layout of the table will be similar to Figure 8-26.

Figure 8-26. The designer of the Contacts table defined in the SQL Azure database.

Now you can configure the SQL Database project as the target database for the SharePoint app simply by selecting the new database project in the SQL Database property of the SharePoint app project.

To autopopulate the database with sample data, you can add an SQL script to the project and configure it in the SQL Data Script property of the SharePoint app. In real scenarios, you will probably use this script to autopopulate lookup tables, as well as to execute any other SQL script that you will need to commit just after having created the SQL Azure database.

The .NET code to retrieve the SqlConnection object of a SQL Azure database for an autohosted app provides the code excerpt you can use to retrieve an instance of a SqlConnection object for accessing the SQL Azure database—for example, for using it with Entity Framework. In fact, you cannot configure the connection string directly in the web.config file of your autohosted app, because while writing your app you won’t know where the SQL Azure database will be deployed. To solve this issue, the SharePoint Client Object Model provides you with a class named AppInstance, which has a method called TryGetAppDatabaseConnectionDirect that accepts the current ClientContext instance and a couple of output arguments for trying to retrieve the current database connection.

 SqlConnection connection;
Boolean isReadOnly;
var contextToken = TokenHelper.GetContextTokenFromRequest(
HttpContext.Current.Request);
var hostWeb = request["SPHostUrl"];
using (var clientContext = TokenHelper.GetClientContextWithContextToken(
    hostWeb, contextToken, request.Url.Authority)) {
        AppInstance.TryGetAppDatabaseConnectionDirect(clientContext,
            out connection, out isReadOnly);
        // This code block closes the connection in case of usage with Entity 
        // Framework
        if (connection.State != System.Data.ConnectionState.Closed) {
            connection.Close();
        }
}

While working locally, the SQL Azure database will be deployed on your local machine under a connection string like the following:

Data Source=(localdb)Projects;Initial Catalog=DevLeap.SP2013.ContactsAppAutoHosted.DB;Integrated Security=True;Pooling=False;Connect Timeout=30;ApplicationIntent=ReadWrite

While on Windows Azure, the connection string will map to a real SQL Azure environment. Now you are free to use the database from any kind of code for accessing the database, such as direct System.Data.SqlClient objects, Entity Framework, or whatever else you like. In the companion source code, you will find a complete code example of using Entity Framework for accessing the Contacts entities, rendering the output in a read-only grid. Take a look at the result in Figure 8-27.

Figure 8-27. The sample SharePoint app based on SQL Azure rendering the list of Contacts entities.

As shown in Figure 8-27, the output is extremely simple, leaving a great deal of room for improvement to the UI and UX. For example, the app is missing a command bar to interact with the SharePoint environment, as well as a Back button to return to the host web. Such UI components were provided by default for SharePoint-hosted apps. You could create chrome to mimic a SharePoint-hosted app, but you don’t have to: SharePoint provides a control called a Chrome control, which renders based on some HTML/JavaScript/CSS code and can be included in any SharePoint app page. The Default.aspx page of the autohosted app with the Chrome control in place provides the source code of the Default.aspx page of an autohosted app with the Chrome control in place.

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Default.aspx.cs" Inherits="DevLeap.SP2013.ContactsAppAutoHostedWeb.Pages.Default" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Contacts Autohosted App with Chrome</title>
    <script type="text/javascript"
        src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>
    <script type="text/javascript"
        src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js"></script>
    <script type="text/javascript">
        "use strict";
        var hostweburl;
        //load the SharePoint resources
        $(document).ready(function () {
            //Get the URI decoded URL.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );
            // The SharePoint js files URL are in the form:
            // web_url/_layouts/15/resource
            var scriptbase = hostweburl + "/_layouts/15/";
            // Load the js file and continue to the 
            //   success handler
            $.getScript(scriptbase + "SP.UI.Controls.js", renderChrome)
        });
        // Callback for the onCssLoaded event defined
        //  in the options object of the chrome control
        function chromeLoaded() {
            // When the page has loaded the required
            //  resources for the chrome control,
            //  display the page body.
            $("body").show();
        }</title>
        //Function to prepare the options and render the control
        function renderChrome() {
            // The Help, Account and Contact pages receive the 
            //   same query string parameters as the main page
            var options = {
                "appIconUrl": "../AppIcon.png",
                "appTitle": "Contacts Autohosted App with Chrome",
                "appHelpPageUrl": "Help.html?"
                    + document.URL.split("?")[1],
                // The onCssLoaded event allows you to
                //  specify a callback to execute when the
                //  chrome resources have been loaded.
                "onCssLoaded": "chromeLoaded()",
                "settingsLinks": [
                    {
                        "linkUrl": "Account.html?"
                            + document.URL.split("?")[1],
                        "displayName": "Account settings"
                    },
                    {
                        "linkUrl": "Contact.html?"
                            + document.URL.split("?")[1],
                        "displayName": "Contact us"
                    }
                ]
            };
            var nav = new SP.UI.Controls.Navigation(
                                    "chrome_placeholder",
                                    options
                                );
            nav.setVisible(true);
        }
        // Function to retrieve a query string value.
        // For production purposes you may want to use
        //  a library to handle the query string.
        function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&");
            var strParams = "";
            for (var i = 0; i < params.length; i = i + 1) {
                var singleParam = params[i].split("=");
                if (singleParam[0] == paramToRetrieve)
                    return singleParam[1];
            }
        }
    </script>
</head>
<body>
    <form id="form1" runat="server">
        <div id="chrome_placeholder"></div>
        <div style="margin: 10px;">
            <h1 class="ms-accentText">Contacts App</h1>
            <h2 class="ms-accentText">The list of Contacts</h2>
            <div id="MainContent">
                <asp:GridView ID="gridContacts" runat="server" CellPadding="4"
                    ForeColor="#333333" GridLines="None">
                    <AlternatingRowStyle BackColor="White" />
                    <EditRowStyle BackColor="#2461BF" />
                    <FooterStyle BackColor="#507CD1" Font-Bold="True" 
                    ForeColor="White" />
                    <HeaderStyle BackColor="#507CD1" Font-Bold="True" 
                    ForeColor="White" />
                    <PagerStyle BackColor="#2461BF" ForeColor="White"
                        HorizontalAlign="Center" />
                    <RowStyle BackColor="#EFF3FB" />
                    <SelectedRowStyle BackColor="#D1DDF1" Font-Bold="True"
                        ForeColor="#333333" />
                    <SortedAscendingCellStyle BackColor="#F5F7FB" />
                    <SortedAscendingHeaderStyle BackColor="#6D95E1" />
                    <SortedDescendingCellStyle BackColor="#E9EBEF" />
                    <SortedDescendingHeaderStyle BackColor="#4870BE" />
                </asp:GridView>
            </div>
        </div>
    </form>
</body>
</html>

The code contains a couple of JavaScript inclusions in the header of the page. Taken from the official Microsoft CDN, these JavaScript files support jQuery and AJAX. Next, an explicit script injects the JavaScript file SP.UI.Controls.js from the source host web URL. Moreover, the script prepares the Chrome control for rendering, providing the ID of a DIV control that will be the placeholder for the Chrome control, as well as a set of options. These options define the title, icon, help page URL, and additional Settings menu links for rendering in the Chrome control. Compare Figure 8-28 with Figure 8-27 to fully appreciate the results of this makeover. Notice the custom items in the Settings menu, as well as the Back button to return to the host site.

Figure 8-28. The Default.aspx page of the autohosted app, with the Chrome control in action.

One last thing to emphasize about the Chrome control is that when you change the design of the host site, the app site will reflect the same choices because the Chrome control loads its styles dynamically.

Invoking the Deploy command for a SharePoint-hosted app or an autohosted app is easy: simply right-click the app project in Visual Studio Solution Explorer and click the Deploy command on the menu. The result will be a complete deployment of your app on the target platform. For example, your autohosted app will be packaged and published for you on Office 365 and on Windows Azure. Now you can test this project while running completely in the cloud or while on the target platform. Suppose you deployed the autohosted Contacts app on your developer site in Office 365. After deployment, the autohosted app will be executed from a dedicated hosting infrastructure, using Windows Azure websites and SQL Azure on the back end, instead of being executed from your localhost using IIS Express and the local SQL Server Express. Of course, in this last scenario, you will not be able to debug the server code. The URL of your app will become something like the following:

https://52b8b0c7-78da-4a07-9d2b-3190e07625f5.o365apps.net/

As you can see, the URL references the Office 365 autohosted apps environment (o365apps.net), and every app installation receives a unique GUID-based host name. If you want to remove the app, you can invoke the Retract menu item, still available by right-clicking the app project in Solution Explorer, or you can explicitly remove it from the target host site.

When you’re ready to publish your app, right-click the SharePoint app project in Solution Explorer and choose Publish from the menu to open the publishing wizard. For SharePoint-hosted and autohosted apps, the wizard only allows you to click the Finish button to create the package for publishing. The result will be an APP file placed inside the app.publish subfolder of the Debug or Release folder of the project, depending the compilation type you are using.

The APP file is an ordinary ZIP file, but with .app extension instead. In fact, if you change the file extension from .app to .zip and you explore the content, you will find files and folders describing the app for publishing. For an autohosted app, for instance, you’ll see the AppIcon.png file, the AppManifest.xml file, a DACPAC file for provisioning the database on SQL Azure, a ZIP file for provisioning the website onto Windows Azure websites (if necessary), resource files, and so on. For SharePoint-hosted apps, you will see the AppIcon.png file, the AppManifest.xml, and the resources files, as well as a WSP file, which will be used for provisioning all the SharePoint artifacts onto the app website. Figure 8-30 compares the outline of two APP files: one for a SharePoint-hosted app (on the left) and one for an autohosted app (on the right).

Figure 8-30. The contents of a SharePoint-hosted app’s APP file (left) and an autohosted app’s APP file (right), once renamed into ZIP.

In either case, you can manually upload the resulting APP file to a developer site for testing, publish it to a corporate app catalog, or submit it to the Office Store to make it publicly available.

While publishing a provider-hosted app, you are presented with a rich wizard. The first page asks you to select or create a new publishing profile (see Figure 8-31). It even offers you options for multiple profiles for testing, staging, production, and so on.

Figure 8-31. The first step of the publishing wizard for publishing a provider-hosted app.

The second page (Figure 8-32) asks you to provide information about the hosting environment, including the URL of the target site, the client ID, and the client secret for secure communication between SharePoint and the provider-hosted app. You can retrieve the client ID and client secret values from the Seller Dashboard available on the Office Store, or you can generate them from the target host site. (For more information, see the “Security infrastructure” section later in the chapter.

Figure 8-32. The second step of the publishing wizard for publishing a provider-hosted app.

The last page is just a recap of your settings. This time, the result of the publishing wizard will be a set of files: an APP file for publishing the app, a DEPLOY file (web deploy file) for the website deployment, and a ZIP file with the contents of the website.

To publish an app to the corporate app catalog, you need to have the URL of the corporate app catalog site collection configured for your current web application or tenant, as well as a set of authorized credentials for publishing apps. Then you can simply upload the APP file to the catalog into the Apps For SharePoint library. The results will be similar to the corporate app catalog in Figure 8-33. In the section “App management configuration and deployment,” you will learn how to configure an app catalog on your farm.

Figure 8-33. The list of apps for SharePoint published in a corporate app catalog.

Once you have configured a corporate app catalog for a web application or tenant, and you have published some apps on it, you can add an app to a target site by clicking Site Contents, and then Add An App. You can then choose apps published through the corporate app catalog by browsing a specific category of apps called From Your Organization. Figure 8-34 shows how the apps are presented to the end user. Notice that, for the sake of completeness, the app catalog in the figure also contains an autohosted app, which is not available in an on-premises scenario. Thus, the app catalog highlights this issue and does not allow the user to install that app.

Figure 8-34. The user’s view of the apps in a corporate app catalog.

If you are a farm administrator, you will be able to monitor app installation and usage from SharePoint Central Administration (SPCA).

What if you want to make your apps available for the entire world? In that case, you need to rely on the Office Store provided by Microsoft (http://www.office.com/store). To do so, you first need to create a seller account for publishing apps. With a valid and enabled account, you can access the Seller Dashboard at https://sellerdashboard.microsoft.com. There, after logging in with a valid Windows Live ID, you will be able to submit an app, manage your already submitted apps, register client IDs, and monitor metrics of selling and downloads of your apps. Figure 8-35 shows the first step for creating an app profile. You have to choose whether you are publishing an app for Office or SharePoint, or an app for Windows Azure. Note, however, that the Seller Dashboard is the same for both types of apps.

Figure 8-35. The first page of the wizard for submitting an app to the Office Store through the Seller Dashboard.

Click Next to go to the page for providing information about the app (title, version number, logo, category, screen shots, target markets, trial periods, and so on). As shown in Figure 8-36, during this phase you also must provide the APP file package.

Figure 8-36. The second page of the wizard for submitting an app to the Office Store through the Seller Dashboard.

On the third page (Figure 8-37), you can provide descriptive information, up to five screen shots with a fixed size of 512×384 pixels, license information, and so on.

Figure 8-37. The third page of the wizard for submitting an app to the Office Store through the Seller Dashboard.

On the wizard’s last page, shown in Figure 8-38, you can configure the price for your app or choose to make it freely available.

Figure 8-38. The last step for submitting an app to the Office Store through the Seller Dashboard.

Your app will be verified and checked against an approval process based on the rules outlined at the following URL: http://msdn.microsoft.com/en-us/library/office/apps/jj220035. Upon approval completion, your app will be available worldwide either on Office 365 or on-premises (as long as the farm administrators of the on-premises farm have enabled the capability to freely install apps from the Office Store).

As a seller, you will be able to monitor how your app sells on the market, as well as your revenues in the case of for-purchase apps.

The app model of SharePoint also provides a standard path for upgrading your apps. Whether you need to upgrade your app to fix a bug or add new features, the process is the same:

Upon changing the version number and republishing the app, you will have a new subfolder in the app.publish folder. From there you will be able to get the new upgraded APP file.

For apps published through the Office Store, however, you will need to submit the new and updated version for approval before publishing to the end users. For apps published through a corporate app catalog, you simply update the APP file in the catalog’s target Apps For SharePoint library. Regardless of the publishing environment you are using, existing installations will not be upgraded automatically. Instead, end users who have installed the app will be informed by the environment that a newer version is available, as shown in Figure 8-39.

Figure 8-39. The notification of an available upgrade for an installed app.

Authorized users can upgrade the app by clicking the Get It button. During the upgrade process, the user will have to trust the app again. In fact, the upgraded version could have changed the permissions requirements. During the upgrade process, the app will show an informational message while on the Site Contents page.

The upgrade process for SharePoint-hosted apps is simple and easy. For autohosted apps, the upgrade of the Windows Azure website is handled on the Azure platform. The upgrade process for provider-hosted apps also involves the external publishing infrastructure, so be careful while upgrading these apps. In fact, you should not upgrade a provider-hosted app site introducing breaking changes, unless you are absolutely sure that all of your existing customers and users have already upgraded the app on their SharePoint environments. Usually, in these cases it would be better to keep different versions of the app online, on the provider side, to support customers who are reluctant to upgrade to the new versions of your app.