How to receive text (XAML)

Applies to Windows and Windows Phone

To receive shared text, your app needs to support the Share contract, handle share activation events, and use the ShareOperation object to retrieve the shared text content.

Text is perhaps the most common of all data formats that users share. In addition to being the first choice for content such as status updates, it is a recommended option for apps that share links, HTML, and other information.

When writing a share target app, you should support text as a part of sharing because it ensures that users can select your app in a wide variety of situations. That said, do not support text if you think it will only confuse users. For example, if your app deals mostly with files, a text representation of those files isn't going to meet user expectations.

What you need to know

Technologies

Prerequisites

  • You should be familiar with Visual Studio and its associated templates.
  • You should be familiar with C#/C++ development.

Instructions

Step 1: Support the Share contract

Before your app can receive shared content, you have to declare that it supports the Share contract. This contract lets the system know that your app is available to receive content. If you're using a Visual Studio template to create your app, here's how you support the Share contract:

  1. Open the manifest file. It should be called something like package.appxmanifest.
  2. Open the Declarations tab.
  3. Choose Share Target from the Available Declarations list.
  4. Click Add to add support for the Share Target contract in your app.

Step 2: Specify that your app supports text

To specify that your app supports text as a data format:

  1. Open the manifest file.
  2. In the Data Formats section, click Add New.
  3. Type text. Don't include the period (.).

The preceding steps add the following section to the manifest.


<Extensions>
  <Extension Category="windows.shareTarget">
    <ShareTarget>
      <DataFormat>text</DataFormat>
    </ShareTarget>
  </Extension>
</Extensions>

Note  You can specify a different entry point when your app is activated for the Share contract. To do this, modify the Start page entry in App settings section of the Share Target declaration in the package manifest.

Step 3: Adding the necessary namespaces

For a target app, you'll need the Windows.ApplicationModel.Activation, Windows.ApplicationModel.DataTransfer, and Windows.ApplicationModel.DataTransfer.ShareTarget namespaces:


using Windows.ApplicationModel.Activation;
using Windows.ApplicationModel.DataTransfer;
using Windows.ApplicationModel.DataTransfer.ShareTarget;


Step 4: Handling share activation

When a user selects your app to share content, the system activates your app by calling the app's Application.OnShareTargetActivated method. You need to override this method to get the content that a user wants to share.


protected override void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
    // Code to handle activation goes here.	
}

Step 5: Get the ShareOperation object.

The ShareOperation object contains all the data that your app needs, to get the content that a user wants to share.


ShareOperation shareOperation = args.ShareOperation;

Step 6: Defer processing of share data.

The Application.OnShareTargetActivated method must return quickly. After retrieving the ShareOperation object, return from the Application.OnShareTargetActivated method and asynchronously complete the share data processing.


await Task.Factory.StartNew(async () =>
{
    // Code to process share data goes in here.
});

Step 7: Check to see if the share data contains text.

The ShareOperation object contains a DataPackageView object. This object is essentially a read-only version of the DataPackage object that the source app used to create the data. Use this object to see if the content being shared is available in text format.


if (shareOperation.Data.Contains(StandardDataFormats.Text))
{
    // Code to process text goes here.
}


Even if your app supports only text, you should add a statement similar to the preceding code. It makes it easier to support other data types and file formats later, if you choose to do this.

Step 8: Process the text.

To get the text, call the DataPackageView.GetTextAsync method.


string sharedText = await shareOperation.Data.GetTextAsync();

Of course, what you do with the text depends on your app.

Step 9: Call ReportCompleted.

After your app finishes processing the content that the user wants to share, call ReportCompleted so the system knows your app is no longer needed.


shareOperation.ReportCompleted();

Note  If you're going to test the code in this section, we recommend that you do not immediately add the code that calls ReportCompleted. This is because the system closes your app after ReportCompleted is called, which prevents the test from proceeding. When you move your code into production, make sure you add the call to ReportCompleted.

Remarks

The best way to see how an app can receive text as part of sharing is by checking out our code sample. However, the following example should also give you a good idea of how a completed function might look.

Example


// In App.xaml.cpp:

void App::OnShareTargetActivated(ShareTargetActivatedEventArgs^ args)
{
    // This example navigates to a ShareTargetPage if the app is invoked as a Share target.
    auto rootFrame = ref new Frame();
    TypeName pageType = { "ShareTargetCPP.ShareTargetPage", TypeKind::Custom };
    rootFrame->Navigate(pageType, args->ShareOperation);
    Window::Current->Content = rootFrame;
    Window::Current->Activate();
}

// In ShareTargetPage.xaml.cpp:

void ShareTargetPage::OnNavigatedTo(NavigationEventArgs^ e)
{
    // We recommend retrieving the ShareOperation object only in the activation handler, 
    // returning as quickly as possible, and retrieving all data from the share target 
    // asynchronously.

    shareOperation = dynamic_cast<ShareOperation^>(e->Parameter);

    create_task([this]()
    {
        sharedDataTitle = shareOperation->Data->Properties->Title;
        sharedDataDescription = shareOperation->Data->Properties->Description;

        std::vector<task<void>> dataPackageTasks;
        if (shareOperation->Data->Contains(StandardDataFormats::Text))
        {
            dataPackageTasks.push_back(create_task(shareOperation->Data->GetTextAsync()).then([this](String^ text)
            {
                sharedText = text;
            }));		
        }
        return when_all(dataPackageTasks.begin(), dataPackageTasks.end());
    }).then([this] ()
    {
        // This example uses "DataPackageTitle", "DataPackageDescription", and 
        // "ContentValue" TextBlock controls to output the title, description, and 
        // shared text respectively.
        DataPackageTitle->Text = sharedDataTitle;
        DataPackageDescription->Text = sharedDataDescription;
        ContentValue->Text = "The following text was shared: " + sharedText; 
    }, task_continuation_context::use_current()); // Run the continuation on the UI thread as it updates the UI.
}


Related topics

Sharing content target app sample
Sharing and exchanging data
How to receive HTML
How to receive a link
Quickstart: Receiving shared content
DataPackage
Windows.ApplicationModel.DataTransfer
Windows.ApplicationModel.DataTransfer.Share
Guidelines for debugging target apps

 

 

Show:
© 2014 Microsoft