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 | |
| 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:
- Identify the item (book, movie, and so on) that the user wants to share.
- Collect the information related to the item and package it in JavaScript Object Notation (JSON) format.
- 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:
- Edit your package manifest to declare that your app is a share target. See Quickstart: Receiving shared content to learn how to do this.
- 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 useWindows-8-Preview-Book. - 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.
Related topics
Sharing content source app sample