Export (0) Print
Expand All

Registering Standard Applications



Every Microsoft Surface application must have an associated XML file to register the application with Surface Shell. This file enables Surface Shell to recognize the application and display it in Launcher. The XML file also includes elements to register tagged objects that your application uses and to register your application to use with object routing. To register the application with Surface Shell, you must create a shortcut file (.lnk) that points to the application's XML file, and then put that shortcut file in the appropriate ProgramData directory.

noteNote
Service applications use only a subset of the elements in the XML file that are used for standard applications. For more information, see Registering Service Applications. The attract application can be customized through Surface Configuration Editor. For more information, see the topic titled "Configuring the Attract" in the Surface Administration Guide.

When you create a new Microsoft Visual Studio 2010 Express (or a full edition of Visual Studio 2010) project by using one of the project templates for a Surface application, an XML file for the application is automatically created and named ProjectName.XML (where ProjectName is the name of your project). When you want to deploy the application, you must create a shortcut file (.lnk) that points to the application's XML file, and then put that shortcut file in the %PROGRAMDATA%\Microsoft\Surface\v2.0\Programs folder on a device made for Surface to register the application with Surface Shell.

You can manually edit the XML registration file at any time (for example, if you want to change the application's description and the image that appears in Launcher).

ImportantImportant
When you test and debug your application, you do not have to create the XML file to register it. When you open and debug your application from Visual Studio 2010 on a device made for Surface or in Input Simulator, the Surface software automatically registers your application so that it works correctly with Launcher. Alternatively, you could create a shortcut file to the executable in your application's Debug folder, and put that shortcut file in the %PROGRAMDATA%\Microsoft\Surface\v2.0\Programs folder. In both cases, the image in Launcher will be the default application image, and not the image specified in the XML registration file. For more information, see Testing and Debugging Surface Applications.

This topic includes the following sections:

XML Registration File

The XML registration file contains default information for everything that the Surface software requires to register an application. However, you must change some of this information by manually editing the XML file.

Surface supports two types of applications: standard applications and service applications. The XML file uses the following elements to distinguish these types of applications:

  • <Application>

  • <ServiceApplication>

The XML file also contains the following important entries.

noteNote
Registration files for standard applications can use all of these elements. However, service applications use only a subset of the elements. For more information, see Registering Service Applications.

 

XML entry Default value Description

<Title>

ProjectName

The application title that appears in Launcher (labeled 1 in the following illustration). By default, this entry is the name of the Microsoft Visual C# 2010 Express Edition (or Microsoft Visual Studio 2010) project for the application. You should edit this entry to create a friendly name for your application.

<Description>

Description

The description of the application that appears in Launcher when the application is selected (labeled 2 in the following illustration). By default, this entry is the name of the Visual C# 2010 Express Edition (or Visual Studio 2010) project for the application. You should change this entry to an accurate description of the application.

The description can have a maximum of three lines of text. Any extra text is truncated. In addition, the description is left-justified, so a description of only two to four words might look off-center.

<ExecutableFile>

ProjectName .exe

The file name of the application's executable file, with or without the fully qualified path. The executable file must reside in the local file system. If the executable file exists in the same folder as the application registration XML file, no path is required. If the executable file is missing or invalid, the application will not appear in Launcher.

<Arguments>

Empty

Command-line entries for the application. By default, this entry is empty.

<IconImageFile>

Resources\icon.png

An image that represents the application in Launcher (labeled 3 in the following illustration). The image must be in PNG format (.png). The dimensions of the image should be 308 pixels by 190 pixels, but if your image is larger or smaller, Launcher resizes the image appropriately. If this file is missing or invalid, Launcher uses a default image.

<Tags>

None

Any tags that are associated with the application. For more information, see the "Registering Tags for an Application" section of this topic.

Launcher with applications in default order

Applications in Launcher

  1. Application title

  2. Application description

  3. Application icon image

The following code shows the default XML registration file. The <Application> element is the root element for standard applications. A service application uses <ServiceApplication> as the root element instead of <Application>.

<?xml version="1.0" encoding="utf-8" ?>
<!--
This file contains the information needed to install your application
with the Surface Shell. Please refer to the documentation for deployment
instructions.
-->
<ss:ApplicationInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ss="http://schemas.microsoft.com/Surface/2007/ApplicationMetadata">
  <Application>
    <Title>SurfaceApplication</Title>
    <Description>Application description.</Description>
    <ExecutableFile>SurfaceApplication.exe</ExecutableFile>
    <Arguments></Arguments>
    <IconImageFile>InstalledAppInfo\AppIcon.png</IconImageFile>  
  </Application>
</ss:ApplicationInfo>
ImportantImportant
You must manually copy a shortcut to the application's XML file to the %PROGRAMDATA%\Microsoft\Surface\Programs folder to register the application with the Microsoft Surface software and to test or deploy the application as part of the Microsoft Surface experience (that is, to see the application in and start it from Launcher like users will).

You must also edit the XML file if you change the location of the executable file, images, or other files that you add to the project, or if you want to edit the name and description that appear in Launcher.

If you have copied a shortcut to the XML file and the application does not appear in Launcher, the most likely cause is an error in the XML file. Check the event log. Any log events that are associated with bad XML files will be under Applications and Services Logs/Microsoft/Surface/Shell/Operational.

Registering Tags for an Application

In the XML registration file, you can associate a standard application with an unlimited number of tagged objects.

noteNote
We strongly recommend that you register all the tags that your application can use in the application's XML file, even if the application does not use object routing.

By registering all the tags that an application can use, you can make sure that the object routing UI does not appear accidentally and interrupt a user's experience when the user places a tag on the application.

To register tags for an application, add the appropriate elements from the following table under the <Tags> element in the XML file of a standard application.

 

XML entry Usage Description

<Tags>

<Tags></Tags>

The Tags element is the base element that tells Surface Shell that this application wants to register and use a particular tag.

<Tag>

<Tag Attribute="AttributeValue"></Tag>

The Tag element specifies that you want to associate a tag with this application. All attributes are hexadecimal values and must match the tag attribute values that the application expects. The following table lists the default values for each attribute. If an attribute is not set, Surface will assume the default value for it.

 

Attribute Default value

Series

"0x0"

Value

"*"

Schema

"0x0"

ExtendedValue

"0x0"

<Actions>

<Actions></Actions>

The Actions element specifies the actions to associate with the tags. Include this element inside the Tag element that you want to associate the specified action with.

Include the Actions element only if you also include the Launch tag.

noteNote
For this release of Microsoft Surface, Launch is the only valid element that you can include in the Actions element.

<Launch>

<Launch />

The Launch element specifies that the application will use object routing with the tag. This means that Surface will display an object routing menu when an object with the specified tag is placed on the device's screen while in Surface mode. For more information, see the following "Registering an Application for Object Routing" section and the Starting an Application Using Tagged Objects topic.

Registering an Application for Object Routing

To use object routing with your application, the application's XML registration file must specify the tags that support object routing. The values and series that you specify for the tags are the same as the values and series that you specify for object routing in object set XML files. For more information, see Specifying Physical Attributes of Tagged Objects.

For each tag value or series that you specify in the XML registration file, include a <Launch /> action in the XML registration file. (For more information about the <Launch />, see the preceding "Registration Tags for an Application" section.) The following code example shows an application that defines a tag that will cause the application to start when the tag is placed on the screen.

<?xml version="1.0" encoding="utf-8" ?>
<!--
This file contains the information needed to install your application
with the Surface Shell. Please refer to the documentation for deployment
instructions.
-->
<ss:ApplicationInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ss="http://schemas.microsoft.com/Surface/2007/ApplicationMetadata">
  <Application>
    <Title>SurfaceApplication</Title>
    <Description>Application description.</Description>
    <ExecutableFile>SurfaceApplication.exe</ExecutableFile>
    <Arguments></Arguments>
    <IconImageFile>InstalledAppInfo\AppIcon.png</IconImageFile>  
    <Tags><Tag Value="0xC1"><Actions><Launch/></Actions></Tag><Tag Value="0xC2" /></Tags>
  </Application>
</ss:ApplicationInfo>

Did you find this information useful? Please send us your suggestions and comments.

© Microsoft Corporation. All rights reserved.
Show:
© 2014 Microsoft