Registering a Microsoft Surface Application

Registering a Microsoft Surface Application

Surface 1.0 SP1

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. To register the application with Surface Shell, you must copy the application's XML file to the appropriate ProgramData directory. The XML file also includes elements to register tagged objects that your application uses and to register your application to use with object routing.

noteNote
Attract applications and service applications use only a subset of the elements in the XML file that are used for standard applications. For more information, see Configuring Attract Applications and Registering Service Applications.

When you create a new Microsoft Visual C# 2008 Express Edition (or Microsoft Visual Studio 2008) project by using the template for a Microsoft 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 copy this XML file to the %PROGRAMDATA%\Microsoft\Surface\Programs folder on a Microsoft Surface unit to register the application with Surface Shell.

You can manually edit this XML file at any time (for example, if you want to change the application's description and graphics that appear 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 C# 2008 (or Visual Studio 2008) on a Microsoft Surface unit or in Surface Simulator, the Microsoft Surface software automatically registers your application so that it works correctly with Launcher. For more information, see Testing and Debugging.

This topic includes the following sections:

XML Registration File

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

Microsoft Surface supports three types of applications: standard application, attract application, and service applications. The XML file uses the following elements to distinguish these types of applications:

  • <Application>

  • <AttractApplication>

  • <ServiceApplication>

The XML file also contains the following important entries.

noteNote
Registration files for standard applications can use all of these elements. However, attract applications and service applications use only a subset of the elements. For more information, see Configuring Attract Applications and 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 Visual C# 2008 (or Visual Studio 2008) project for the application. You should edit this entry to create a friendly name for your application.

<Description>

ProjectName

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# 2008 (or Visual Studio 2008) 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 full path and file name to the application's executable file. The executable file must reside in the local file system. If this 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 icon that represents the application in Launcher when the application is not selected (and does not appear in the center of the filmstrip) (labeled 4 in the following illustration). The image must be in PNG format (.png), but it can be any size. Launcher resizes the image appropriately. However, icon images should have a 1:1 aspect ratio in order to resize properly. If this file is missing or invalid, Launcher uses a default image.

<Preview>

Resources\iconPreview.png

A preview for the application in Launcher when the application is selected (labeled 3 in the following illustration). This preview can be an image, a slide show, or a movie. If this file is missing or invalid, Launcher uses a default image. For more information about the application preview, see Setting the Application Preview 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 - Close-up example (labeled)
  1. Application title

  2. Application description

  3. Application preview image

  4. Application icon image

The following code shows the default XML registration file. The <Application> element is the root element for standard applications. An attract application uses <AttractApplication> as the root element instead of <Application>, and 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>SurfaceApplication</Description>
    <ExecutableFile>SurfaceApplication.exe</ExecutableFile>
    <Arguments></Arguments>
    <IconImageFile>Resources\icon.png</IconImageFile>
    <Preview>
      <PreviewImageFile>Resources\iconPreview.png</PreviewImageFile>
    </Preview>
  </Application>

  <!--
  Uncomment this section and comment out the Application element above
  if you are creating an Attract Mode Application.
  -->
  <!--
  <AttractApplication>
    <ExecutableFile>SurfaceApplication.exe</ExecutableFile>
    <Arguments></Arguments>
  </AttractApplication>
  -->
</ss:ApplicationInfo>
ImportantImportant
You must manually copy 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 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

<IdentityTag>

<IdentityTag Series=" SeriesNumber "></IdentityTag>

The <IdentityTag> element specifies that you want to associate an identity tag with this application. SeriesNumber is an integer and must match the tag series that the application expects.

<ByteTag>

<ByteTag Value=" ByteTagValue "></ByteTag>

The <ByteTag> element specifies that you want to associate a byte tag with this application. ByteTagValue is an integer and must match the tag value that the application expects.

<Actions>

<Actions><Launch /></Actions>

The actions to associate with the tags. Include this element inside the <IdentityTag> or <ByteTag> element that you want to associate the specified action with.

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 where this element appears. For more information, see the following "Registering an Application for Object Routing" section and the Using Object Routing with 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 the registry. 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 several byte tags and identity tags.

...
<Application>
...
    <Tags>
        <IdentityTag Series="A36E47C3D38E34BE">
            <Actions>
                <Launch /> 
            </Actions>
        </IdentityTag>
        <IdentityTag Series="562D23EA239B1A79">
            <Actions>
                <Launch /> 
            </Actions>
        </IdentityTag>
        <ByteTag Value="A">
            <Actions>
                <Launch /> 
            </Actions>
        </ByteTag>
        <ByteTag Value="5">
            <Actions>
                <Launch /> 
            </Actions>
        </ByteTag>
     </Tags>
</Application>
...

Community Additions

ADD
Show:
© 2016 Microsoft