Extending the photo apps picker for Windows Phone 7

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic contains the following sections.

• Extending the photo apps picker
• Step 1: Specify capabilities
• Step 2: Register extensions
• Step 3: Map the launch URI
• Step 4: Handle the URI parameters
• Testing the photo apps picker on your phone

Extending the photo apps picker

The photo apps picker appears in the built-in photo viewer. You launch it from the app bar, by tapping on the apps link. The following image shows the photo viewer apps link and the name of the photo apps picker extension (which is described later in this topic).

The following steps describe how to integrate your app into the photo apps picker.

Step 1: Specify capabilities

Windows Phone OS 7.1 apps need to specify the ID_CAP_MEDIALIB capability to access photos in the media library. Capabilities are specified in the app manifest file, WMAppManifest.xml.

<!-- For accessing photos in the media library. -->
<Capability Name="ID_CAP_MEDIALIB" />

Step 2: Register extensions

To appear in the photo apps picker, register for the Photos_Extra_Viewer extension. Extensions are specified in the app manifest file, WMAppManifest.xml. Just after the Tokens element, inside the Extensions element, the photo apps picker extension is specified with the following Extension element.

<Extension ExtensionName="Photos_Extra_Viewer" 
           ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}" 
           TaskID="_default" />

The Windows Phone Manifest Designer does not support extensions; use the XML (Text) Editor to edit them. For more info, see How to modify the app manifest file for Windows Phone 8.

Step 3: Map the launch URI

When the user taps your app in the photo apps picker, a deep link URI is launched to open your app and send a token to the photo that the user was viewing. Your app can detect a photo apps picker launch when the URI contains the string: token. The following example is a launch URI from the photo apps picker (as seen from a URI mapper when the default navigation page is MainPage.xaml).

/MainPage.xaml?token=%7B273fea8d-134c-4764-870d-42224d13eb1a%7D

In this example, the token parameter value is the token. That string can be used to retrieve the photo from the media library. This is described later in the topic.

Because the photo apps picker targets the default navigation page (in this case, MainPage.xaml), that page will be launched if you don’t implement any URI mapping. If your app’s default navigation page can handle the photo referenced by the token, URI mapping may not be necessary.

However, if you want to launch a different page for editing a photo, you’ll need to map the URI to that page. The following example shows how this is done with a custom URI mapper class.

using System;
using System.Windows.Navigation;

namespace CustomMapping
{
    class CustomUriMapper : UriMapperBase
    {
        public override Uri MapUri(Uri uri)
        {
            string tempUri = uri.ToString();
            string mappedUri;

            // Launch from the photo apps picker.
            // Incoming URI example: /MainPage.xaml?token=%7B273fea8d-134c-4764-870d-42224d13eb1a%7D
            if ((tempUri.Contains("token")) && !(tempUri.Contains("RichMediaEdit")))
            {
                // Redirect to PhotoPage.xaml.
                mappedUri = tempUri.Replace("MainPage", "PhotoPage");
                return new Uri(mappedUri, UriKind.Relative);
            }
            // Otherwise perform normal launch.
            return uri;
        }
    }
}

In this example, the URI mapper maps the incoming URI to a page named PhotoPage.xaml by replacing the page name within the URI. The URI returned by that method is then used by the root frame of the app to launch the first page when the app starts. The root frame uses the custom URI mapper because it is assigned as the app initializes. The following code shows how the URI mapper is assigned in the InitializePhoneApplication method of the App.xaml.cs file.

private void InitializePhoneApplication()
{
    if (phoneApplicationInitialized)
        return;

    // Create the frame but don't set it as RootVisual yet; this allows the splash
    // screen to remain active until the application is ready to render.
    RootFrame = new PhoneApplicationFrame();
    RootFrame.Navigated += CompleteInitializePhoneApplication;

    // Handle navigation failures
    RootFrame.NavigationFailed += RootFrame_NavigationFailed;

    // Assign the custom URI mapper class to the application frame.
    RootFrame.UriMapper = new CustomMapping.CustomUriMapper();

    // Ensure we don't initialize again
    phoneApplicationInitialized = true;
}

Step 4: Handle the URI parameters

When the page is launched, the page can access all of the parameters in the URI (that launched the page) using the QueryString property of the page’s NavigationContext object. The following example shows how the value of the token parameter is used with the MediaLibraryGetPictureFromToken(String) method to extract the photo from the media library. This code is from the PhotoPage.xaml.cs file of the Photo Extensibility Sample.

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get a dictionary of query string keys and values.
    IDictionary<string, string> queryStrings = this.NavigationContext.QueryString;

    // Ensure that there is at least one key in the query string, and check whether the "token" key is present.
    if (queryStrings.ContainsKey("token"))
    {
        // Retrieve the photo from the media library using the token passed to the app.
        MediaLibrary library = new MediaLibrary();
        Picture photoFromLibrary = library.GetPictureFromToken(queryStrings["token"]);

        // Create a BitmapImage object and add set it as the image control source.
        BitmapImage bitmapFromPhoto = new BitmapImage();
        bitmapFromPhoto.SetSource(photoFromLibrary.GetImage());
        image1.Source = bitmapFromPhoto;
    }
}

Testing the photo apps picker on your phone

This procedure describes how you can launch your app from the photo apps picker on Windows Phone OS 7.1.

Note

When debugging Windows Phone OS 7.1 apps, keep in mind that re-launching your app will break the debugging process on your first app instance. Also, Emulator 7.1 does not support photo extensibility testing: that emulator does not contain a Photos/Pictures Hub.

To test the photo apps picker on your phone

1. Confirm that you have photos on your phone or take a picture with the Windows Phone camera.

2. Tether it to your computer and wait for it to be recognized.

3. Run the WPConnect.exe tool as described in How to test apps that use the photo chooser or camera capture task for Windows Phone 8. This tool disconnects the Zune software from the media database on your phone. WPConnect.exe allows you to use the Pictures Hub while your phone is tethered to your computer.

4. Ensure that the app is set to deploy to the device, select Debug from the menu, and select Start Debugging.

5. Once the app is visible, tap Start to navigate to the Start screen.

6. On the Start screen, tap the Pictures app and then tap All. Tap the Camera Roll section to find your picture, and then tap the photo thumbnail to expand the photo.

7. Tap the three dots at the bottom of the page on the app bar. A menu should appear with an apps link at the bottom of the list. Select apps.

8. On the apps page, tap the name of your app. This will launch a URI containing a token to the photo you were just viewing.