Quickstart: Sharing content (XAML) (Windows)

Article
10/13/2015

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

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.

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

You should be familiar with Visual Studio and its templates.
You should be familiar with developing in C#/C++.

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.

Adding the DataTransfer namespace

The first thing you need to do, of course, is add the right namespaces to your app so you can create and process the objects related to sharing. At a minimum, you should add the Windows.ApplicationModel.DataTransfer namespace:

using Windows.ApplicationModel.DataTransfer;

using namespace Windows::ApplicationModel::DataTransfer;

This namespace has all you need for basic sharing. Remember, though, if you want to share content such as images or files, you'll need to add those namespaces as well. Here's a list of the namespaces you might need:

Windows.Storage. Needed for working with StorageFile and other objects.
Windows.Storage.Pickers. Used to open the file picker so users can select images and files.
Windows.Storage.Streams. Often used when sharing images, files, and custom-formatted data.

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.

DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();

DataTransferManager^ dataTransferManager = DataTransferManager::GetForCurrentView();

This class supports a DataRequested event, which is fired when the user wants to invoke Share. In a Windows Store app, this occurs automatically when the user invokes the Share charm. If you're developing for Windows Phone, there is no built-in Share charm, so you'll need to add a control for the user to tap and trigger the handler.

dataTransferManager.DataRequested += new TypedEventHandler<DataTransferManager, 
DataRequestedEventArgs>(this.ShareTextHandler);

auto dataRequestedToken = dataTransferManager->DataRequested += ref new TypedEventHandler<DataTransferManager^, 
    DataRequestedEventArgs^>(this, &MainPage::ShareTextHandler);

The above example registers an event handler that is called whenever a DataRequested event occurs. This handler gets a DataRequestedEventArgs object, which in turn contains the DataRequest object your app uses to set the data that the user wants to share.

The title property is mandatory and must be set.

private void ShareTextHandler(DataTransferManager sender, DataRequestedEventArgs e)
{
    DataRequest request = e.Request;
    
    // The Title is mandatory
    request.Data.Properties.Title = "Share Text Example";

    // Now add the data you want to share.
}

void MainPage::ShareTextHandler(DataTransferManager^ sender, DataRequestedEventArgs^ e)
{
    DataRequest^ request = e->Request;
    
    // The Title is mandatory
    request->Data->Properties->Title = "Share Text Example";

    // Now add the data you want to share.
}

Adding content

When your app receives a DataRequest object, it's ready to add the content that the user wants to share. 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.

//To see this code in action, add a call to RegisterForShare to your constructor or other
//initializing function.
private void RegisterForShare()
{
    DataTransferManager dataTransferManager = DataTransferManager.GetForCurrentView();
    dataTransferManager.DataRequested += new TypedEventHandler<DataTransferManager, DataRequestedEventArgs>(this.ShareTextHandler);
}

private void ShareTextHandler(DataTransferManager sender, DataRequestedEventArgs e)
{
    DataRequest request = e.Request;
    // The Title is mandatory
    request.Data.Properties.Title = "Share Text Example";
    request.Data.Properties.Description = "A demonstration that shows how to share text.";
    request.Data.SetText("Hello World!");
}

//To see this code in action, add a call to RegisterForShare to your constructor or other
//initializing function.
void MainPage::RegisterForShare()
{
    DataTransferManager^ dataTransferManager = DataTransferManager::GetForCurrentView();
    auto dataRequestedToken = dataTransferManager->DataRequested += ref new TypedEventHandler<DataTransferManager^, DataRequestedEventArgs^>(
        this, &MainPage::ShareTextHandler);
}

void MainPage::ShareTextHandler(DataTransferManager^ sender, DataRequestedEventArgs^ e)
{
    DataRequest^ request = e->Request;
    // The Title is mandatory
    request->Data->Properties->Title = "Share Text Example";
    request->Data->Properties->Description = "A demonstration that shows how to share.";
    request->Data->SetText("Hello World!");
}

Note To run this sample, add it to your project, and make sure you call RegisterForShare in your constructor, in OnNavigatedTo, or other initializing function.

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

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

Sometimes, it might not make sense to prepare the data that 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, configure the DataPackage object to call a function any time a target app requests a specific format.

e.Request.Data.SetDataProvider(StandardDataFormats.Bitmap, 
        new DataProviderHandler(this.OnDeferredImageRequestedHandler));

e->Request->Data->SetDataProvider(StandardDataFormats::Bitmap, 
        ref new DataProviderHandler(this, &MainPage::OnDeferredImageRequestedHandler));

This code uses a DataRequestedEventArgs object, which your app receives when a DataRequested event occurs. For more details, see How to share files.

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.

Note

The Charms bar does not exist on Windows Phone 8.1, so you must include the share option programmatically. It can either be accessible at all times as part of an app bar, or be associated with a specific control on a particular page.

private void ShareProgrammatically()

   Windows.ApplicationModel.DataTransfer.DataTransferManager.ShowShareUI();
}

void MainPage::ShareProgrammatically()

   Windows::ApplicationModel::DataTransfer::DataTransferManager::ShowShareUI();
}

Handling 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, on Windows 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 content. For example, the app might require the user to select content for sharing but the user didn't select any. 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.

Note

The FailWithDisplayText method is not supported on Windows Phone 8.1.