Home Library Learn Downloads Support Community
Sign in | United States - English | |
3 out of 24 rated this helpful Rate this topic

How to: Determine Application Capabilities

December 15, 2011

For Windows Phone applications, you should specify the capabilities required by your application, such as networking, the location sensor, or the camera. If you do not accurately specify the capabilities, your application might not work correctly or it might fail the submission process to the Windows Phone Marketplace. You specify the application capabilities in the application manifest file (WMAppManifest.xml). Depending on whether you are targeting Windows Phone OS 7.1 or Windows Phone OS 7.0, you can use the Marketplace Test Kit or the Windows Phone Capability Detection Tool to detect the application capabilities. This topic describes how to determine the capabilities of your application.

To complete these procedures, you must have the Windows Phone SDK. For more information, see Installing the Windows Phone SDK.

Application capabilities are features that a Windows Phone application requires, such as networking, the location sensor, or the camera. You specify the application capabilities in the application manifest file (WMAppManifest.xml). By default, when you create a Windows Phone project, the application manifest file includes a list of all the phone capabilities supported by Windows Phone. For the full list of capabilities and their descriptions, see Application Manifest File for Windows Phone.

Windows Phone provides a capabilities-driven security model where a user must opt-in to certain functionality within the application. For certain scenarios, Windows Phone APIs invoked by applications may require specific security permissions or user disclosure when run. The Windows Phone operating system grants security permissions to the application according to the capabilities listed in that application manifest file. Depending on the API that you use and the capabilities that you specify, your application submission to the Marketplace might fail.

When you submit an application to the Marketplace, the capabilities of the application are programmatically detected. The application submission process uses Microsoft Intermediate Language (MSIL) code analysis to detect the phone capabilities required by the application. The application submission process replaces the capabilities list, whether it is the auto-generated list or a list that you have modified, with the specific capabilities required for your application. This means that if the application manifest submitted with the application does not contain capabilities that are used by your application, these capabilities will be added as part of the submission process.

There are two exceptions for capabilities being added or modified during submission. The first exception is that if you remove the following networking capability from the manifest file, it will not be added during the submission process. This enables you to opt-out of networking support for your application.

  • ID_CAP_NETWORKING

The second exception is that you can specify the forward-facing camera hardware requirement and it will not be modified by the submission process.

  • ID_HW_FRONTCAMERA

For more information about the front-facing camera, see Camera and Photos Overview for Windows Phone.

Instead of relying on the application submission process to detect the phone capabilities required for your application, you can use tools during development and test the application. If your application targets Windows Phone OS 7.1, you can use the Capability Validation test in the Marketplace Test Kit to detect and replace the auto-generated capabilities list in the application manifest file with the specific capabilities required by your application. If your application targets Windows Phone OS 7.0, you can use the Windows Phone Capability Detection Tool to do this.

Note Note:

You should always test applications based on the exact phone capabilities required by your application. Various end-user issues can occur if an application is not tested based on the specific capabilities required by your application.

The Marketplace Test Kit is a suite of tests that enable you to evaluate your Windows Phone OS 7.1 application for Marketplace readiness. The Marketplace Test Kit contains a Capability Validation test that runs as part of its automated test suite. For more information about the Marketplace Test Kit, see Windows Phone Marketplace Test Kit. If you want to view the rules that are applied by Capability Validation test for evaluating the capabilities used by an application, they are in a file named Rules.xml that you can find at one of the following locations.

  • Program Files\Microsoft SDKs\Windows Phone\v7.1\Tools\Marketplace

  • Program Files (x86)\Microsoft SDKs\Windows Phone\v7.1\Tools\Marketplace

To use the Marketplace Test Kit to determine application capabilities

  1. In Visual Studio, create a release build of the Windows Phone OS 7.1 application you want to test the capabilities of. For information about how to create a release build, see How to: Build and Deploy a Windows Phone Application Using Visual Studio.

  2. In Solution Explorer, select the start-up project and on the Project menu, choose the Open Marketplace Test Kit option. The Marketplace Test Kit opens.

  3. Click the Automated Tests tab and click Run Tests. This will run all the automated tests on your application, including the Capability Validation test.

    Note Note:

    If you have not specified art or screenshots for your application, you should expect the Iconography and Screenshots tests to fail. These test results are not relevant to the capability results.

  4. View the Result Details column of the Capability Validation test. Each capability identified in this column starts with ID_CAP. The following is an example results from running the Capability Validation test. ID_CAP_NETWORKING is the only capability listed in this example.

    Copy 
    [INFORMATION]: Capabilities used by application:
ID_CAP_NETWORKING

  5. In Solution Explorer, open the application manifest file (WMAppManifest.xml) for your application and remove all the capabilities that are not listed in the Result Details column. For the example results in the previous step, you would remove all of the capabilities except networking (ID_CAP_NETWORKING).

  6. Build, test, and deploy your application with the granted capabilities provided by the tool.

The Capability Detection Tool is a rules-based command-line utility that you can use on your applications that target Windows Phone OS 7.0. This tool uses the project output folder containing your assemblies, or an assembly file as input, and outputs the list of security capabilities used by the application. The rules for issuing or deleting the capabilities are captured in a file named Rules.xml that is distributed with the tool. The following table lists the commands and parameters that the Capability Detection Tool supports.

Command

Description

CapabilityDetection.exe /?

Displays simple help descriptions.

CapabilityDetection rules path "file path"

Detects the phone capabilities required by the application.

  • rules path - The path to the Rules.xml file.

  • file path - The path to the project output folder containing your assemblies or an assembly file. If the file path contains spaces, it must be in quotation marks ("").

To use the Capability Detection Tool to determine application capabilities

  1. In Visual Studio, create a release build of the Windows Phone OS 7.0 application you want to test the capabilities of.

  2. Open a command prompt and navigate to the folder that contains the Windows Phone Capability Detection Tool (CapabilityDetection.exe). You can find it at one of the following locations:

    • Program Files\Microsoft SDKs\Windows Phone\v7.0\Tools\CapDetect

    • Program Files (x86)\Microsoft SDKs\Windows Phone\v7.0\Tools\CapDetect

  3. Enter the following command, and specify the location of the project output folder that contains your assemblies or an assembly file in the file path parameter.

    Copy 
    CapabilityDetection.exe Rules.xml "file path"
    NoteNote:

    If the file path contains spaces, you must enclose it in quotation marks (""). If the file path is a folder, you should not include a trailing slash (\).

    The following shows two examples:

    Copy 
    CapabilityDetection.exe Rules.xml "C:\MyApp"
CapabilityDetection.exe Rules.xml "C:\MyApp\MyApp.dll"

  4. Copy the capability output displayed by the tool. The following shows an example of the output:

    Copy 
    ID_CAP_NETWORKING
ID_CAP_WEBBROWSERCOMPONENT

    If no capabilities are detected, no output is displayed.

    NoteNote:

    If you specify the XAP file for the file path, no output is displayed.

  5. Open your project in Visual Studio and open the application manifest file (WMAppManifest.xml).

  6. Remove all the capabilities in the Capabilities element and add the required capabilities from the tool output. For example, using output from the previous step, the element would appear like the following:

    Copy 
    <Capabilities>
      <Capability Name="ID_CAP_NETWORKING"/>
      <Capability Name="ID_CAP_WEBBROWSERCOMPONENT"/>
</Capabilities>

  7. Build, test, and deploy your application with the granted capabilities provided by the tool.

    Important note Important Note:

    In some circumstances, the tool might return the ID_CAP_NETWORKING capability even if your application does not use networking. An example would be if you declared a local URI in the XAML. In such cases, you can remove this capability, but ensure that you fully test and deploy your application after you remove it.

Did you find this helpful?
(1500 characters remaining)