Choosing data formats for sharing (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]

Whether you're writing a source app, which helps users share content, or a target app, which receives that content, you should take the time to consider what data formats and file types you want to support. Here, we'll describe the standard formats that the Windows.ApplicationModel.DataTransfer namespace supports, and how to create and use custom formats when the standard formats don't apply.

Choosing data formats for a source app

If you're writing a source app, you aren't limited to just one data format or file type. While it's likely that one format makes more sense than the others, by supplying the same data in other formats you can help to ensure that users can share by using the target app of their choice. For example, if a user wants to share formatted text, such as from a webpage, you might also want to supply a plain-text version of the content, because not every target app supports formatted text.

Note  The number of additional formats that you support depends on the type of content your users might share. It's important to consider what the content is and what the user expects when they share it. Creating a plain-text version of formatted text, for example, often makes sense. Creating a link to a webpage that contains that text, however, is probably not what the user expects.

 

This table can help you decide what formats you should support as a source app.

Primary data type your app supports Recommended primary DataPackage format Additional recommendations
Unformatted plain text Text WebLink, if the text is a webpage link.
Link WebLink Text
Formatted content/HTML HTML

Text, if the content contains only text.

WebLink, if the content is a link.

File StorageItems
Single Image StorageItems
Multiple files and images StorageItems

 

Custom formats are also supported for situations in which you want to be more specific than the standard formats allow. These custom formats can either be based on standard data schemas, such as those found on http://www.schema.org, or a format that you define that's unique to your app.

Choosing data formats for a target app

For a target app, we recommend that you try to support as many format types as possible. This helps to ensure that your app is available as an option whenever the user wants to share. However, just like source apps, you shouldn't support a particular format if you don't plan to receive that type of data. For example, an app that accepts only text shouldn't register that it supports bitmaps.

Here are some recommendations for what formats you should support.

Primary data type your app supports Recommended primary DataPackage format Additional recommendations
Unformatted plain text Text
Link WebLink Text
Formatted content/HTML HTML

Text

WebLink

File StorageItems
Single Image StorageItems
Multiple files and images StorageItems
Specific file types (such as .docx) StorageItems with specific file name extensions

 

If your app can support multiple formats, and all those formats are present in the content being shared, we recommend that you process only the format that is the most relevant to your app. For example, if your app shares links, and it receives shared content that has both a link and some text, your app should process only the link.

Sometimes, your app might benefit from receiving data that includes more information than the standard formats provide. For example, a library app might want to receive text, but only if that text has information about a book. Custom formats are supported for such situations. These custom formats can either be based on standard data schemas, such as those found on http://www.schema.org, or a format that you define that's unique to your app.

Sharing and receiving data with built-in apps

To share data with the following built-in apps, use these respective formats.

App you want to share with DataPackage format
NFC StorageItems
Bluetooth StorageItems

 

To receive data from the following built-in apps, register your app for these respective formats and/or file extensions.

App you want to receive from DataPackage format or file extension
Internet Explorer WebLink
Photos File extensions .jpg and .png
Contacts File extension .vcf (vCard format)
Office File extensions .docx, .pptx, and .xlsx

 

Using schema-based formats

There are lots of times where the data that you want to share (either as a source or as a target app) is more specific than the standard formats provide. For example, a movie-focused app might want to share information about movies, and want details such as the title, rating, director, and so on. A book-focused app might want to share information about books, including author, title, and publication date. If your app falls into a category like this, we recommend that you support one of the many schemas listed on http://www.schema.org.

If you want to share data using one of these schemas, here's how you do it:

  1. Identify the item (book, movie, and so on) that the user wants to share.
  2. Collect the information related to the item and package it in JavaScript Object Notation (JSON) format.
  3. Use SetData to add the content to a DataPackage. When you do, you have to include a format ID. For now, use http://schema.org/<schema> as the ID. For example, http://schema.org/Book.

If you want to receive data that uses one of these schemas, here are the steps you need to follow:

  1. Edit your package manifest to declare that your app is a share target. See Quickstart: Receiving shared content to learn how to do this.
  2. In your package manifest, add a data format that identifies the schema that your app supports. Use Windows-8-Preview-<schema> as the data format. For example, you could use Windows-8-Preview-Book.
  3. Use getDataAsync to get the content from the DataPackageView object that you receive during a share operation.

Using custom formats

If you're unable to find a schema on schema.org that meets the needs of your app, you also have the option of creating your own custom format. If you decide to do that, there are few key things you need to remember:

  • The name of the custom format is important. The same name must be used by both the source app and the target app.
  • You must publish the format. That way, developers who want to use the format know how they need to package the content.

We cover these and other considerations in more detail in Guidelines for creating custom data formats.

Sharing content source app sample

Sharing content target app sample

Quickstart: Sharing content

Quickstart: Receiving shared content