DataTransferManager DataTransferManager DataTransferManager DataTransferManager Class

Programmatically initiates an exchange of content with other apps.

Syntax

Declaration

public sealed class DataTransferManagerpublic sealed class DataTransferManagerPublic NotInheritable Class DataTransferManager

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.

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

Methods summary

Returns the DataTransferManager object associated with the current window.

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

Events summary

Occurs when a share operation starts.

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

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

    Returns

    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.

    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!");
    }
    
  • 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

    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.

    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);
    }
    

Events

  • DataRequested
    DataRequested
    DataRequested
    DataRequested

    Occurs when a share operation starts.

    public event TypedEventHandler DataRequestedpublic event TypedEventHandler DataRequestedPublic Event DataRequested

    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.

    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!");
    }
    
  • TargetApplicationChosen
    TargetApplicationChosen
    TargetApplicationChosen
    TargetApplicationChosen

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

    public event TypedEventHandler TargetApplicationChosenpublic event TypedEventHandler TargetApplicationChosenPublic Event TargetApplicationChosen

    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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute

Details

Assembly

Windows.ApplicationModel.DataTransfer.dll