How to: Load an app license for testing purposes for task pane and content apps

apps for Office and SharePoint

Learn how to load an app license with your app for testing purposes.

Last modified: August 11, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel Online | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint Online | Project 2013 | Word 2013 | Word 2013 RT

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

The licensing framework for apps for Office and SharePoint gives you a way to include code in your app to verify and enforce how it's used based on the properties of its app license. This article describes two methods of loading a test license with your app for Office:

  • Loading a test license from the Visual Studio project for your app.

  • Load a test license from the file system using the Developer Registry provider.

Both methods of loading a license allow an app to get the license the same way it would if it were launched from the Office Store or a SharePoint app catalog. However, a test license isn't treated in the exactly same way by the apps for Office runtime – they are not tested for expiration or the entitlement type and, thus, won't trigger a token refresh or raise an error in the UI.

To load a test license from your Visual Studio project

  1. Create or open a content or task pane app project in Visual Studio.

  2. In the Solution Explorer, right-click the "Office" project (the first of the two projects in the solution, not the second "Web" project), and then click Open Folder in File Explorer.

  3. Navigate to ...bin\Debug\OfficeAppManifests (substitute "Debug" with "Release" if your project is configured for Release builds). This folder is created automatically after the first time you build or debug your project.

  4. Add a token file to the folder. The token file name must be the same as the manifest file name and have a .tok file extension. The following code shows an example token file. Refer to the App License Schema for details about the attribute values you can set in the t element of the token file.

    <r>
      <t 
        aid="WA900006056"
        pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}"
        cid="32F3E7FC559F4F49"
        et="Trial"
        ad="2012-01-12T21:58:13Z"
        ed="2012-06-30T21:58:13Z"
        sd="2012-01-12T00:00:00Z" 
        te="2012-06-30T02:49:34Z"
        test="true"/>
      <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
    </r>
    
  5. Debug > Start debugging, or press F5.

    Note Note

    At the time of publication, Visual Studio will display a message that there were deployment errors, and the license token specified in the <d> tag won't be loaded. However, the other values in the license are loaded and will be available to your app license check code.

  6. To visually confirm that the test license is loaded, click the pop-out menu in the upper right corner of the app pane, and then click Security Info.

To load a test license from the file system

  1. Create a folder that is accessible via a UNC path (c:\folder or \\server\share).

  2. Add the manifest file for your app to the folder (the file name must have an .xml extension). The following code shows an example manifest file for a content app.

    <?xml version="1.0" encoding="utf-8"?>
    <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ContentApp">
      <Id>9C4675F6-45A0-47EE-B9A4-D834F45467672</Id>
      <Version>15.0</Version>
      <ProviderName>Microsoft</ProviderName>
      <DefaultLocale>en-us</DefaultLocale>
      <DisplayName DefaultValue="GetToken">
      </DisplayName>
      <Description DefaultValue="Get Token">
      </Description>
      <Hosts>
        <Host Name="Workbook"/>
      </Hosts>
      <DefaultSettings>
        <SourceLocation DefaultValue="http://MyServer/GetToken.htm">
        </SourceLocation>
        <RequestedWidth>400</RequestedWidth>
        <RequestedHeight>400</RequestedHeight>
      </DefaultSettings>
      <Permissions>ReadWriteDocument</Permissions>
      <AllowSnapshot>true</AllowSnapshot>
    </OfficeApp>
    
  3. Add the token file to the folder. The token file name must be the same as the manifest file name and must have a .tok file extension. The following code shows an example token file. Refer to the App License Schema for details about the attribute values you can set in the t element of the token file.

    <r>
      <t 
        aid="WA900006056"
        pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}"
        cid="32F3E7FC559F4F49"
        et="Trial"
        ad="2012-01-12T21:58:13Z"
        ed="2012-06-30T21:58:13Z"
        sd="2012-01-12T00:00:00Z" 
        te="2012-06-30T02:49:34Z"
        test="true"/>
      <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
    </r>
    
  4. Create an entry in the registry that points to the manifest under the HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Wef\Developer path. You can use a .reg file like the following example. (Note that the name field, "entry1" and the .xml file name in this example are arbitrary.)

    Windows Registry Editor Version 5.00
    
    [HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Wef\Developer]
    "entry1"="C:\\folder\\AppFile.xml"
    

Next steps

You can now implement app license checks in your app's code and test against the information in your test license.

Show:
© 2015 Microsoft