How to receive files (XAML)
[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]
Sharing files requires a little more preparation than simpler data types, such as text. When sharing files, you need to consider how long it might take to process the files.
If you think your app needs time to process the files that a user wants to share, be sure to call ReportStarted before you begin processing them. This method ensures that the system keeps your app alive until it's finished processing. After your app completes its processing, call ReportCompleted to finish the sharing operation. To learn more, see "Report extended share status" in Quickstart: Receiving shared content.
What you need to know
Technologies
Prerequisites
- You should be familiar with Visual Studio and its associated templates.
- You should be familiar with 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.
- Open the manifest file. It should be called something like package.appxmanifest.
- Click the Declarations tab.
- In the Available Declarations list, click Share Target.
Step 2: Specify file types that your app supports
You can specify the file types that your app supports by specifying their extensions in the app manifest.
- Open the manifest file.
- In the Data Formats section, click Add New.
- Type the file name extension, such as .txt.
- Repeat for any additional file types.
The preceding steps add the following section to the manifest:
<Extensions>
<Extension Category="windows.shareTarget">
<ShareTarget>
<SupportedFileTypes>
<FileType>.txt</FileType>
</ShareTarget>
</Extension>
</Extensions>
Note You don’t need to specify StorageItems in the Data Formats section. Support for this is inferred from the SupportedFileTypes section in the manifest. If your app supports all file types, you can indicate this in the manifest by checking Supports any file type.
Note You can specify a different entry point when your app is activated for the Share Target contract. To do this, modify the Start page entry in App settings section of the Share Target declaration in the package manifest. We highly recommend that you also use a separate code file that handles activation for this page. For an example, check out the Sharing content target app sample.
Step 3: Adding required namespaces
For a target app, you'll need to add 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 async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
// Code to handle activation goes here.
}
Step 5: Get the ShareOperation object
The ShareOperation object contains all the data your app needs to get the content that a user wants to share.
ShareOperation shareOperation = args.ShareOperation;
Step 6: Check to see if the DataPackageView contains a bitmap
The ShareOperation object contains a DataPackageView object. This object is 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 contains StorageItems.
if (shareOperation.Data.Contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.StorageItems))
{
// Data being shared contains one or more StorageItem. Code to process the StorageItems goes here.
}
Checking whether the DataPackage contains the data format you are interested in is good practice, even if your app supports only one format. This makes it easier to support other data formats later.
Step 7: Process the files
To get the files, call the DataPackageView.GetStorageItemsAsync method. The following example compiles the names of the files in a string.
IReadOnlyList<IStorageItem> sharedStorageItems = await shareOperation.Data.GetStorageItemsAsync();
string fileNames = "";
for (int index = 0; index < this.sharedStorageItems.Count; index++)
{
fileNames += sharedStorageItems[index].Name;
if (index < this.sharedStorageItems.Count - 1)
{
fileNames += ", ";
}
}
// Output the name of the files to a text control in your app
Note
Processing files can take time. It is important that you don't force the user to wait until your app is finished loading and processing data. On Windows 8.1, you can call the ReportStarted method to let the system know that your app has started to process the content being shared. The system keeps your app alive until you call ReportCompleted—even if the user dismisses your app to return to the source app. For more information, see "Report extended share status" in Quickstart: Receiving shared content.
Step 8: Call ReportCompleted
When your app finishes processing the shared content, call ReportCompleted. You must call this method so the system knows your app is no longer needed.
shareOperation.ReportCompleted();
Remarks
Check out our Sharing content target app sample code sample to see the entire end-to-end experience of an app receiving files as part of sharing.
Complete example
if (shareOperation.Data.Contains(StandardDataFormats.StorageItems))
{
IReadOnlyList<IStorageItem> sharedStorageItems = await shareOperation.Data.GetStorageItemsAsync();
string fileNames = "";
for (int index = 0; index < this.sharedStorageItems.Count; index++)
{
fileNames += sharedStorageItems[index].Name;
if (index < this.sharedStorageItems.Count - 1)
{
fileNames += ", ";
}
}
// Output the name of the files to a text control in your app
}
Related topics
Sharing content target app sample
Quickstart: Receiving shared content
Windows.ApplicationModel.DataTransfer