Declaring Capabilities in WP7 Apps

If you’ve ever created a Windows Phone 7 application, you’re probably aware that before submitting for Marketplace approval you must enable only those “capabilities” that are actually being used.  Capabilities required by your app must be listed in the WMAppManifest.xml file, found in the Projects folder of your UI project.  For new solutions, all capabilities are by default included, as shown below:

	<Capabilities>
	  <Capability Name="ID_CAP_GAMERSERVICES"/>
	  <Capability Name="ID_CAP_IDENTITY_DEVICE"/>
	  <Capability Name="ID_CAP_IDENTITY_USER"/>
	  <Capability Name="ID_CAP_LOCATION"/>
	  <Capability Name="ID_CAP_MEDIALIB"/>
	  <Capability Name="ID_CAP_MICROPHONE"/>
	  <Capability Name="ID_CAP_NETWORKING"/>
	  <Capability Name="ID_CAP_PHONEDIALER"/>
	  <Capability Name="ID_CAP_PUSH_NOTIFICATION"/>
	  <Capability Name="ID_CAP_SENSORS"/>
	  <Capability Name="ID_CAP_WEBBROWSERCOMPONENT"/>
	  <Capability Name="ID_CAP_ISV_CAMERA"/>
	  <Capability Name="ID_CAP_CONTACTS"/>
	  <Capability Name="ID_CAP_APPOINTMENTS"/>
	</Capabilities>

If you include capabilities that are not actually used in your app, your submission to the marketplace will fail.  Fortunately, the Marketplace Test Kit (found via the context menu of the UI project in Visual Studio) can be used to verify what capabilities are required.  The “Capability Validation” result of the “Automated Tests” lists all capabilities used within you app.  The result below shows two capabilities used by an app.

Capabilities

Unfortunately, if you do not declare a capability that your app does actually use, you can easily run into trouble.  The automated tests of the Marketplace Test Kit will list all the capabilities that you make use of, but they will not indicate that you have missed a required capability.  The test will also still indicate a “passed” status, even though you have not declared a required capability.  Instead, functionality within your app can simply break, with no clear indication of the cause.

It’s usually best to leave all of the capabilities listed in the manifest file until you’re near the completion of your development, and then use the Marketplace Test Kit to determine which ones you can remove.  Since this is the typical development process, it’s unusual to encounter a problem.  If you’re starting with existing code, however, this can be the cause of a real headache.  Perhaps you’re returning to a solution you worked on earlier, in order to add new functionality.  Or perhaps you’ve started with a sample solution you came across online, expanding it with additional functionality.  In either case, if you add code that requires a capability no longer included in the manifest, you may end up chasing down bugs that don’t make much sense.

Recently I was exploring the possibilities of recording and playing back audio on WP7.  A quick search led me to a great starting point, in the form of a demo app for a WP7 voice recorder (http://www.codeproject.com/Articles/175122/Making-a-Voice-Recorder-on-Windows-Phone).  That solution uses the Microphone class of the XNA Framework for recording, and the XNA SoundEffect class for playback.  Although the SoundEffect class offers the interesting ability to adjust the pitch of the sound, it does not provide a way to specify the temporal position within the audio file.  I wanted a scrub bar to allow the user to move the playback position arbitrarily.  Switching to a MediaElement for playback would allow me to do this.

After making the appropriate changes, I was disappointed to find playback wasn’t working.  Subscribing to the MediaFailed event of the MediaElement revealed that a failure was occurring as soon as its source was set.  (The error message was the fairly useless “3100 An error has occurred”.)  After much digging around, I finally realized that MediaElement requires another WP7 capability (“ID_CAP_MEDIALIB”), and by introducing it into my project I needed to add the capability to my manifest file as well.

The lesson I learned is that if I’m starting with an existing WP7 solution and plan on making extensive changes, I should first visit the manifest file and make sure all capabilities are included.  This could prevent some serious debugging headaches.  Also, if I encounter bugs that don’t make much sense, it’s a good idea to run the automated tests of the Marketplace Test Kit, and ensure all capabilities listed in the results are included in the manifest file.  Only when I’m close to submitting for approval do I remove unnecessary capabilities from the manifest (and I comment them out, rather than remove them, making it easier to add them all back in if I revisit the code at a later time).

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>