[This documentation is preliminary and is subject to change.]

Successful apps make it easy for users to share what they are doing with their friends and family. Apps that make it easy for users to share content often see an increased awareness of the app, and that encourages users to use the app more often. Windows 8 Release Preview provides a robust set of APIs that can help you connect your users with the people they care about and the apps they use most.

To learn how to use these APIs, read on. If you’re more interested in learning how your app can receive shared content, see Quickstart: Receiving shared content.

Objective: After reading through this quickstart, you should have a good idea how to share content.

Prerequisites

To use the code described in this section, you'll need:

• Windows 8
• Microsoft Visual Studio Express 2012 RC for Windows 8

Instructions

Choosing data formats

At the core of any sharing operation is the DataPackage object. This object contains the data the user wants to share. The types of content that a DataPackage can contain include:

• Plain text
• Uniform Resource Identifiers (URIs)
• HTML
• Formatted text
• Bitmaps
• Files
• Developer-defined data

A DataPackage object can contain one or more of these formats, in any combination. In addition, a DataPackage can contain a delegate—a function that is called when the receiving app requests data. We recommend using a delegate any time that the data a user wants to share is resource-intensive, as a delegate can help your app share data more efficiently.

Choosing properties

When you package data for sharing, you have the option to supply a variety of properties that provide additional information about the content being shared. Taking advantage of these properties can help target apps improve the user experience. For example, providing a title and description that conveys what the user is sharing can help when the user is sharing content with more than one app. Adding a thumbnail when sharing an image or a link to a web page can provide a visual reference to the user. For more information on what properties are available for you to use, check out our documentation on DataPackage.DataPackagePropertySet.

Setting up for sharing

To support sharing in your app, you first need to get the instance of the DataTransferManager class that’s been assigned to the current window.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();

This class supports a datarequested event, which is fired when a user presses the Share or Connect charm. Your app needs to listen for this event to know when the user wants to share something.

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

The above JavaScript example registers an event handler that is called whenever a datarequested event is fired. This handler gets a DataRequest object, which your app uses to set the data that the user wants to share with the target app.

Sharing text

When your app detects a datarequested event, it gets a DataRequest object. This is the object your app needs to actually share content with another app. Any content that you share must contain two properties: a title and the content itself. (We recommend that you include a description, too.) The following code builds on our previous examples to share text with a target app.

function shareText() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", function (e) {
        var request = e.request;
        request.data.properties.title = "Share Text Example";
        request.data.properties.description = "A demonstration that shows how to share.";
        request.data.setText("Hello World!");
    });
}

We have a number of resources to help you share data in a number of different formats. To learn more, check out:

• How to share text
• How to share a link
• How to share HTML
• How to share an image
• How to share files

For more info on these and other format types, check out Choosing data formats and file types.

Sharing and delegates

Sometimes, it might not make sense to prepare the data the user wants to share right away. For example, if your app supports several different data formats, it is inefficient to create those formats immediately. The better solution is to wait until the target app specifies the format that it wants, and then generate the data. To accomplish this, you configure the DataPackage object to call a function any time a target app requests a specific format.

request.data.setDataProvider(Windows.ApplicationModel.DataTransfer.StandardDataFormats.bitmap, onDeferredImageRequested);

You can see how this type of sharing works in How to share files.

Programmatically invoking the share UI

After you set your content for sharing, it's ready to go. All the user needs to do is select the app to receive the content. For those situations in which using the charm isn't ideal—such as to share a high score on a game—you can also launch the Share charm programmatically.

function showShareUI() {
    Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
}

Handle errors and other issues

In most cases, sharing content is a straightforward process. However, there's always a chance that something unexpected could happen. To help you handle these situations, the DataRequest object supports a FailWithDisplayText method. Use this method to display a text message to the user if something happens that prevents your app from sharing their content. Remember that this method is just a first step—you should always test your app to see if you can take additional actions in the event something goes wrong.

Summary and next steps

You should now have a good understanding of how to sharing works.

To learn more, or to get more specific examples of how to add sharing to your app, you might want to take a look at:

• Sharing content source app sample
• Sharing content target app sample
• Quickstart: Receiving shared content
• How to share text
• How to share a link
• How to share HTML
• How to share an image
• How to share files

Related topics

Choosing data formats for sharing

Guidelines and checklist for sharing content

Quickstart: Receiving shared content

Build date: 5/22/2012