DataTransferManager DataTransferManager DataTransferManager DataTransferManager Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

[Contains prerelease APIs.]
Programmatically initiates an exchange of content with other apps.

public : sealed class DataTransferManager : IDataTransferManager, IDataTransferManager2public sealed class DataTransferManager : IDataTransferManager, IDataTransferManager2Public NotInheritable Class DataTransferManager Implements IDataTransferManager, IDataTransferManager2// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

This example shows a typical way of using the DataTransferManager object.

function setupShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", function (e) {
        var request = e.request;
        request.data.properties.title = "Share Demonstration";
        request.data.setText("Hello World!");
    });
}

Remarks

The DataTransferManager class is a static class that you use to initiate sharing operations. To use the class, first call the GetForCurrentView method. This method returns the DataTransferManager object that is specific to the active window. Next, you need to add an event listener for the datarequested event to the object. This event is fired when a sharing operation starts— typically when the user taps the Share charm, although it is also fired if your app starts a share operation programmatically.

The DataTransferManager class includes a ShowShareUI method, which you can use to programmatically start a share operation. In general, we recommend against using this method. Users expect to initiate share operations by using the Share charm— when you launch the operation programmatically, you can create an inconsistent user experience. We include the method because there are a few scenarios in which the user might not recognize opportunities to share. A good example is when the user achieves a high score in a game.

The DataTransferManager class also has a TargetApplicationChosen event. Use this event when you want to capture what applications a user selects when sharing content from your app.

Note

: This class is not agile, which means that you need to consider its threading model and marshaling behavior. For more info, see Threading and Marshaling (C++/CX) and Using Windows Runtime objects in a multithreaded environment (.NET).

Windows Phone 8

This API is supported in native apps only.

Methods

GetForCurrentView() GetForCurrentView() GetForCurrentView() GetForCurrentView()

Returns the DataTransferManager object associated with the current window.

public : static DataTransferManager GetForCurrentView()public static DataTransferManager GetForCurrentView()Public Static Function GetForCurrentView() As DataTransferManager// You can use this method in JavaScript.
Returns

Examples

This example calls the GetForCurrentView method to get the DataTransferManager object associated with the active window for the app.

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

private void DataRequested(DataTransferManager sender, DataRequestedEventArgs e)
{
    DataRequest request = e.Request;
    request.Data.Properties.Title = "Share Text Example";
    request.Data.Properties.Description = "An example of how to share text.";
    request.Data.SetText("Hello World!");
}
function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(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!");
}

Remarks

Each window has a DataTransferManager object associated with it. When sharing content, you use the GetForCurrentView method to get the DataTransferManager object that is associated with the active window. After you have the appropriate DataTransferManager object, you can add an event listener to it to handle the DataRequested event, which the system fires when a share operation is initiated. Your app uses the DataRequest object returned with this event to set the data that the user wants to share with a target app.

IsSupported() IsSupported() IsSupported() IsSupported()

Returns true if the device supports sharing, false otherwise.

public : static PlatForm::Boolean IsSupported()public static bool IsSupported()Public Static Function IsSupported() As bool// You can use this method in JavaScript.
Returns
PlatForm::Boolean bool bool bool

True if the device supports sharing, false otherwise.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

ShowShareUI() ShowShareUI() ShowShareUI() ShowShareUI()

Programmatically initiates the user interface for sharing content with another app.

public : static void ShowShareUI()public static void ShowShareUI()Public Static Function ShowShareUI() As void// You can use this method in JavaScript.

Examples

This example demonstrates how to call the ShowShareUI method to launch the Share user interface. Notice that this example only launches the interface— it does not add any content to share with another app.

function launchShare() {
    var shareButton = document.createElement("button");
    shareButton.setAttribute("id", "showShareButton");
    shareButton.innerText = "Click to share!";
    shareButton.addEventListener("click", function () {
        Windows.ApplicationModel.DataTransfer.DataTransferManager.showShareUI();
    });
    document.body.appendChild(shareButton);
}

Remarks

We recommend that you use this method only when absolutely necessary. Users expect to launch the Share user interface through the Share charm. Launching the user interface programmatically can create a confusing user experience.

As a general rule, use this method only when it isn't obvious to a user that some content is shareable. For example, if a user gets a high score in a game, it may not be obvious that they can share that high score with their friends. In this situation, it makes sense to use the showShareUI method.

A DataPackage must have its Title set in order to be shared. Ensure Title is set before calling this method.

ShowShareUI(ShareUIOptions) ShowShareUI(ShareUIOptions) ShowShareUI(ShareUIOptions) ShowShareUI(ShareUIOptions)

Prerelease. Programmatically initiates the user interface for sharing content with another app.

public : static void ShowShareUI(ShareUIOptions shareOptions)public static void ShowShareUI(ShareUIOptions shareOptions)Public Static Function ShowShareUI(shareOptions As ShareUIOptions) As void// You can use this method in JavaScript.
Parameters
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16257.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

Remarks

We recommend that you use this method only when absolutely necessary. Users expect to launch the Share user interface through the Share charm. Launching the user interface programmatically can create a confusing user experience.

As a general rule, use this method only when it isn't obvious to a user that some content is shareable. For example, if a user gets a high score in a game, it may not be obvious that they can share that high score with their friends. In this situation, it makes sense to use the showShareUI method.

A DataPackage must have its Title set in order to be shared. Ensure Title is set before calling this method.

Events

DataRequested DataRequested DataRequested DataRequested

Occurs when a share operation starts.

public : event TypedEventHandler DataRequested<DataTransferManager,  DataRequestedEventArgs>public event TypedEventHandler DataRequested<DataTransferManager,  DataRequestedEventArgs>Public Event DataRequested<DataTransferManager,  DataRequestedEventArgs>// You can use this event in JavaScript.

Examples

This example uses an inline function to handle a datarequested event.

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

private void DataRequested(DataTransferManager sender, DataRequestedEventArgs e)
{
    DataRequest request = e.Request;
    request.Data.Properties.Title = "Share Text Example";
    request.Data.Properties.Description = "An example of how to share text.";
    request.Data.SetText("Hello World!");
}
function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareTextHandler);
}

function shareTextHandler(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!");
}

Remarks

This event is fired when a sharing operation starts— typically when the user taps the Share charm, although it is also fired if your app starts a share operation programmatically. To handle this event, you need to add an event listener to the DataTransferManager object for the active window. You can get this object through the GetForCurrentView method.

When handling a datarequested event, the most important property you need to be aware of is its request property. This property contains a DataRequest object. Your app uses this object to provide the data that the user wants to share with a selected target app.

ShareProvidersRequested ShareProvidersRequested ShareProvidersRequested ShareProvidersRequested

An event that is triggered when the share providers are requested. This is used as a callback and providers are added by subscribing to this event and calling ShareProvidersRequestedEventArgs.Providers.Add() in the event handler.

public : event TypedEventHandler ShareProvidersRequested<DataTransferManager,  ShareProvidersRequestedEventArgs>public event TypedEventHandler ShareProvidersRequested<DataTransferManager,  ShareProvidersRequestedEventArgs>Public Event ShareProvidersRequested<DataTransferManager,  ShareProvidersRequestedEventArgs>// You can use this event in JavaScript.
Additional features and requirements
Device family
Windows 10 Creators Update (introduced v10.0.15063.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v4)

TargetApplicationChosen TargetApplicationChosen TargetApplicationChosen TargetApplicationChosen

Occurs when the user chooses a target app in the Share charm.

public : event TypedEventHandler TargetApplicationChosen<DataTransferManager,  TargetApplicationChosenEventArgs>public event TypedEventHandler TargetApplicationChosen<DataTransferManager,  TargetApplicationChosenEventArgs>Public Event TargetApplicationChosen<DataTransferManager,  TargetApplicationChosenEventArgs>// You can use this event in JavaScript.

Remarks

When the user chooses a target app to share content with, the system fires a TargetApplicationChosen event. The app receiving the event can use this event to record information about the target app for business intelligence. A common use of this event is to record which applications are used to complete different sharing actions, which in turn can help the source app create better experiences for the user.

See Also