Wednesday, May 21, 2014

My First SharePoint 2013 Timer Job - Setup

Topic:Environment, Configuration, and Programming
Level:Advanced
Intended Audience:Administrator, Architect, Developer, and IT Professional

I have decided to tackle what I considered to be a great starting point for first time app creators. I wanted to show you how I created the equivalent of a traditional SharePoint timer job (what used to be done via a sharepoint solution in sharepoint 2010) inside of SharePoint 2013's App model. Specifically for an on-premise SharePoint farm. This is mostly tailored towards the Developer but, there is a lot of useful information here for Admins, Architects, and IT Pros as well.

Microsoft Developer Network (MSDN) and various blog posts detail bits and pieces of what the IT Professional / Admin, the Developer, or the Architect need to know. Here I will take you from end-to-end. And, hopefully explain a bit along the way. I am assuming very little familiarity here with SharePoint 2013 but at least some understanding of the previous versions of SharePoint.

So what is on-premise?


On-premise software is installed and ran on servers within your organization rather than using servers that reside in the cloud. Opposite of on-premise would be a cloud based computing platform such as Microsoft Azure.

So what is a provider-hosted app?


A provider-hosted app is an application that is deployed and hosted outside the SharePoint farm. So where your solutions used to get installed directly onto the farm in the form of deployed WSP files, these applications do not. They are installed to the host web, but their remote components are hosted on another server. See the following example:


I will be making a few assumptions at this point. But just in case something seems off to you I will let you know in advance what servers I am on and those other types of details. Also, a lot of these steps will not need to be repeated for all of your projects moving forward. For example, you likely will not have to create a certificate every time. You can reuse the same self-signed certificate from your first project. A lot of these steps, however, will need to be repeated or changed a little based on the environment you are working in.

Setting Up Your Project (Development Environment)


The first thing we need to do is generate a self-signed certificate. The SharePoint project is going to require a certificate and for the initial phase of debugging a self-signed certificate works best.

  1. When you are debugging a high-trust app for SharePoint in Visual Studio, the remote web application is hosted in IIS Express on the machine where Visual Studio is installed. So the remote web application computer does not have an IIS Manager where you can create the certificate. For this reason, you use the IIS on the SharePoint test server to create the certificate. In IIS Manager, select the ServerName node in the tree view on the left.
  2. Select the Server Certificates icon, as shown below.

    Server Certificates option in IIS
  3. Select the Create Self-Signed Certificate link from the set of links on the right side, as shown below.

    Create Self-Signed Cerificate link
  4. Name the certificate HighTrustApps, and then choose OK.
  5. Right-click the certificate, and then select Export, as shown below.

    Exporting a test certificate
  6. In Windows, or at the command line, create a folder called C:\Certs.
  7. Back in IIS Manager, export the file to C:\Certs and give it a password. In my example above I used the password of password.
  8. If your test SharePoint installation is not on the same computer where Visual Studio is running, create a folder C:\Certs on the Visual Studio computer and move the HighTrustApps.pfx file to it. This is the computer where the remote web application runs when you are debugging Visual Studio.
Now we need to create a corresponding .cer file.

  1. On the SharePoint server, be sure that the app pool identity for the following IIS app pools have Read rights to the C:\Certs folder:
    • SecurityTokenServiceApplicationPool
    • The app pool that serves the IIS web site that hosts the parent SharePoint web application for your test SharePoint website. For the SharePoint - 80 IIS website, the pool is called OServerPortalAppPool.
    • You can see the Identity to use by looking under the Application Pools located under the ServerName node in the tree view on the left. Then just update the folder permissions to give that Identity Read access.
  2. In IIS manager, select the ServerName node in the tree view on the left.
  3. Double-click Server Certificates.
  4. In Server Certificates view, double-click HighTrustApps to display the certificate details.
  5. On the Details tab, choose Copy to File to launch the Certificate Export Wizard, and then choose Next.
  6. Use the default values and choose Next.
  7. Choose Browse, browse to C:\Certs, name the certificate HighTrustAppsCert, and then choose Save. The certificate is saved as a .cer file.
  8. Choose Next.
  9. Choose Finish.
If this has not been done yet we need to configure services in SharePoint 2013 for server-to-server app use.

  1. Ensure that the app management service and the user profile application are configured. The steps are as follows:
    • In Central Administration, under Application Management, select Manage service applications.
    • On the Service Applications page, ensure that the following services are started:
      • User Profile Service Application
      • App Management Service
    • Under Application Management, select Manage services on server.
    • On the Services on Server page, ensure that the following services are started:
      • User Profile Service
  2. Ensure that at least on profile is created in the User Profile Service Application. The steps are as follows:
    • In Central Administration, under Application Management, select Manage service applications.
    • Next, select User Profile Service Application.
    • On the Manage Profile Service: User Profile Service Application page, under People, select Manage User Profiles.
    • On the Manage User Profiles page, select New Profiles.
    • On the Add User Profile page, type your account name and email address.
    • Select Save and Close.
      • NOTE: If you get a message saying that the profile you are trying to create already exists, simply Cancel and Go Back.
    • Back on the Manage User Profiles page, you should see Total number of profiles: 1.
Again, if you have not done so already you need to install the Visual Studio 2013 developer tools found at http://msdn.microsoft.com/en-US/office/dn448479. This allows some key components of app development.

As an additional tip, you can enable verbose logging inside of Visual Studio 2013 by doing the following:
  1. Open the registry using regedit and navigate to HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\12.0\SharePointTools.
  2. Add a DWORD key named EnableDiagnostics.
  3. Give the key the value 1.


If you want to create and deploy SharePoint-hosted apps on your SharePoint 2013 installation, you must create an isolated domain on the server where your apps for SharePoint will run. In this example I will show how to do this on the development workstation you are on. For development purposes, you can modify your hosts file as you need to route your development computer to a test instance of an app for SharePoint.

  1. Ensure that the spadmin and sptimer services are running by opening a command prompt and typing the following commands:

    net start spadminv4

    net start sptimerv4
  2. Create your isolated app domain by running the SharePoint Management Shell as an administrator and type the following command:

    Set-SPAppDomain "apps.mydevdomain.com"
  3. Ensure that the SPSubscriptionSettingsService and AppManagementServiceInstance services are running by typing the following command in the SharePoint Management Shell.

    Get-SPServiceInstance | where{$_.GetType().Name -eq "AppManagementServiceInstance" -or $_.GetType().Name -eq "SPSubscriptionSettingsServiceInstance"} | Start-SPServiceInstance
  4. You must specify an account under which the SPSubscriptionService and AppManagementServiceInstance service instances will run. This account must be an SPManaged account. You can create an SPManagedAccount by typing the following command in the SharePoint Management Shell. Please note, you will be prompted for the account DOMAIN\user and password.

    $account = New-SPManagedAccount
  5. Next you need to specify an account, application pool, and database settings for the SPSubscriptionService and AppManagementServiceInstance services by typing the following code into the SharePoint Management Shell. If you created a SPManagedAccount in the preceding step, use that account name here.

    $account = Get-SPManagedAccount "DOMAIN\user"

    $appPoolSubSvc = New-SPServiceApplicationPool -Name SettingsServiceAppPool -Account $account

    $appPoolAppSvc = New-SPServiceApplicationPool -Name AppServiceAppPool -Account $account

    $appSubSvc = New-SPSubscriptionSettingsServiceApplication -ApplicationPool $appPoolSubSvc -Name SettingsServiceApp -DatabaseName SettingsServiceDB

    $proxySubSvc = New-SPSubscriptionSettingsServiceApplicationProxy -ServiceApplication $appSubSvc

    $appAppSvc = New-SPAppManagementServiceApplication -ApplicationPool $appPoolAppSvc -Name AppServiceApp -DatabaseName AppServiceDB

    $proxyAppSvc = New-SPAppManagementServiceApplicationProxy -ServiceApplication $appAppSvc
    • NOTE: When I ran this for the first time I got a "The timer job did not complete running within the allotted time." error. To resolve that error message or others you come across I had to do a few additional troubleshooting steps.
      • I first checked to ensure that the SharePoint Timer Service under Administrative Tools | Services was in fact running.
      • I checked that my cache cluster was up for Distributed Cache. To do so type in the following command into the SharePoint Management Shell:

        Get-CacheHostConfig -ComputerName $env:computername -CachePort 22233

        That command should give you information about the current cache host. If that command does not work you may have to create a new cache cluster. The details of which can be found at http://msdn.microsoft.com/en-us/library/ff921027.aspx.
      • If your cache is up and running, try the following commands:

        Remove-SPDistributedCacheServiceInstance

        Add-SPDistributedCacheServiceInstance
      • If you still get unexpected errors try the following command:

        Restart-CacheCluster
      • Also you should check your service account's file read access to "C:\Program Files\AppFabric 1.1 for Windows Server\DistributedCacheService.exe.Config". Your service accounts may need to be granted read access to the top-level AppFabric directory if you are seeing script errors in the SharePoint Management Shell.
      • And finally, if all else fails try the following commands:

        Export-CacheClusterConfig -path D:\clusterconfig.xml

        Stop-CacheCluster


        Check within the config file if the host name is correct (change to the netbiosname) and that the service account is the same as is listed for your AppFabric Caching Service in services.msc.

        To import the configuration again use the following command:

        Import-CacheClusterConfig -path D:\clusterconfig.xml

        Start-CacheCluster


        To confirm everything is working properly try the following:

        Get-Cache

        Get-CacheClusterHealth
  6. Next you need to specify your tenant by typing the following command into the SharePoint Management Shell.

    Set-SPAppSiteSubscriptionName -Name "app" -Confirm:$false
You now need to add your isolated app domain to your IE bypass list. This ensures that you can navigate to that domain after you deploy a SharePoint-hosted app. You can skip this if your environment does not use a proxy server.
  1. In Internet Explorer, go to Tools.
  2. Choose Internet options.
  3. On the Connections tab, choose the LAN Settings button.
  4. Clear the Automatically detect settings check box.
  5. Select the Use a proxy server for your LAN check box.
  6. Choose the Advanced button, and then add *.YourAppDomain.com to the Exceptions list.
  7. Choose the OK button.
  8. Choose the OK button to close the Local Area Network (LAN) Settings dialog box.
  9. Choose the OK button to close the Internet Options dialog box.
EDIT: If you get a 401.1 Unauthorized Logon Failed message or logon prompts you may have to disable the loopback check. Just follow Method 2 of the following article to do this. That article can be found at http://support.microsoft.com/kb/896861.

That's it! Your server (isolated app) to server (SharePoint 2013 server) foundation is now setup. In my next post I will walk you through creating a high-trust provider hosted app for your SharePoint installation that uses a app only policy. Taking us one step closer to mimicking a SharePoint 2010 timer solution.