DataPackagePropertySet DataPackagePropertySet DataPackagePropertySet DataPackagePropertySet Class

Definition

Defines a set of properties to use with a DataPackage object.

public sealed class DataPackagePropertySetpublic sealed class DataPackagePropertySetPublic NotInheritable Class DataPackagePropertySetpublic sealed class DataPackagePropertySet
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

In addition to the content being shared, each instance of a DataPackage object supports a set of properties. Target apps can use these properties to learn more about the content of the DataPackage.

This class directly supports several default properties, such as a Thumbnail, a Title, and a Description. You can also create your own custom properties by using the Insert(String, Object) method or one of the Add methods. Target apps can access specific properties through the Lookup(String) or TryGetValue methods.

Collection member lists

For JavaScript, DataPackagePropertySet supports using an index to access items.

Properties

ApplicationListingUri ApplicationListingUri ApplicationListingUri ApplicationListingUri

Gets or sets the Uniform Resource Identifier (URI) of the app's location in the Windows Store.

public Uri ApplicationListingUri { get; set; }public Uri ApplicationListingUri { get; set; }Public ReadWrite Property ApplicationListingUri As Uripublic Uri ApplicationListingUri { get; set; }
Value
Uri Uri Uri Uri

The Uniform Resource Identifier (URI) of the app in the Windows Store.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

ApplicationName ApplicationName ApplicationName ApplicationName

Gets or sets the name of the app that created the DataPackage object.

public string ApplicationName { get; set; }public string ApplicationName { get; set; }Public ReadWrite Property ApplicationName As stringpublic string ApplicationName { get; set; }
Value
string string string string

Specifies the name of the app that created the DataPackage object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Gets or sets the application link to the content from the source app.

public Uri ContentSourceApplicationLink { get; set; }public Uri ContentSourceApplicationLink { get; set; }Public ReadWrite Property ContentSourceApplicationLink As Uripublic Uri ContentSourceApplicationLink { get; set; }
Value
Uri Uri Uri Uri

The Uniform Resource Identifier (URI) of the application link to shared content.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

ContentSourceApplicationLink is a companion property that you use to attribute shared content. It's shared when the app finds it meaningful for the user to return to the content that's currently displayed in the app. When the user makes a selection, the ApplicationLink format isn't populated, because the value for ApplicationLink format isn't the same as the user's selection. Populating this info doesn't mean that the deep link into the app represents the user's selection, only that the content comes from there.

Provides a web link to shared content that's currently displayed in the app.

public Uri ContentSourceWebLink { get; set; }public Uri ContentSourceWebLink { get; set; }Public ReadWrite Property ContentSourceWebLink As Uripublic Uri ContentSourceWebLink { get; set; }
Value
Uri Uri Uri Uri

The Uniform Resource Identifier (URI) of the web link to shared content.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

ContentSourceWebLink is a companion property that you use to attribute shared content. It's shared when the app provides a web link to the content being shared. When the user makes an explicit selection, the WebLink format isn't populated, because the value for the WebLink format isn't the same as the user's selection. Populating this info doesn't mean that the web page is the user's selection, only that the content comes from there.

Description Description Description Description

Gets or sets text that describes the contents of the DataPackage.

public string Description { get; set; }public string Description { get; set; }Public ReadWrite Property Description As stringpublic string Description { get; set; }
Value
string string string string

Text that describes the contents of the DataPackage.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

We recommend adding a description to a DataPackage object if you can. Target apps can use this description to help users identify what content they're sharing.

Examples

The following example shows how you can set the description for the content in a DataPackage.

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

EnterpriseId EnterpriseId EnterpriseId EnterpriseId

Gets or sets the enterprise identity (see Enterprise data protection).

public string EnterpriseId { get; set; }public string EnterpriseId { get; set; }Public ReadWrite Property EnterpriseId As stringpublic string EnterpriseId { get; set; }
Value
string string string string

The enterprise Id.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

FileTypes FileTypes FileTypes FileTypes

Specifies a vector object that contains the types of files stored in the DataPackage object.

public IVector<string> FileTypes { get; }public IVector<string> FileTypes { get; }Public ReadOnly Property FileTypes As IVector<string>public IVector<string> FileTypes { get; }
Value

Contains the types of files stored in the DataPackage object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Many target apps accept a number of different file formats. Even so, they might prefer one format over another. By adding the file types supported in a DataPackage to the FileTypes property, you can help those target apps select the most appropriate file format for a given operation.

If your app shares content using one of the formats that the DataPackage object supports directly, such as Text or Html, you should use the StandardDataFormats class when adding file types to this property. If your app supports a custom data format, you can add that format using a string. In cases where your app uses a delegate to add content to the DataPackage, you must ensure that the string you use in the FileTypes property matches the value of the formatId parameter of the SetDataProvider(String, DataProviderHandler) method.

LogoBackgroundColor LogoBackgroundColor LogoBackgroundColor LogoBackgroundColor

Gets or sets a background color for the sharing app's Square30x30Logo.

public Color LogoBackgroundColor { get; set; }public Color LogoBackgroundColor { get; set; }Public ReadWrite Property LogoBackgroundColor As Colorpublic Color LogoBackgroundColor { get; set; }
Value
Color Color Color Color

The color of the logo's background.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

PackageFamilyName PackageFamilyName PackageFamilyName PackageFamilyName

Gets or sets the package family name of the source app.

public string PackageFamilyName { get; set; }public string PackageFamilyName { get; set; }Public ReadWrite Property PackageFamilyName As stringpublic string PackageFamilyName { get; set; }
Value
string string string string

The package family name.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Size Size Size Size

Gets the number of items that are contained in the property set.

public uint Size { get; }public uint Size { get; }Public ReadOnly Property Size As uintpublic uint Size { get; }
Value
uint uint uint uint

The number of elements in the property set.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Gets or sets the source app's logo.

public IRandomAccessStreamReference Square30x30Logo { get; set; }public IRandomAccessStreamReference Square30x30Logo { get; set; }Public ReadWrite Property Square30x30Logo As IRandomAccessStreamReferencepublic IRandomAccessStreamReference Square30x30Logo { get; set; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The logo is padded with the color in LogoBackgroundColor.

The source app should provide the logo that's appropriate for the current plateau level of the share UI.

Thumbnail Thumbnail Thumbnail Thumbnail

Gets or sets a thumbnail image for the DataPackage.

public IRandomAccessStreamReference Thumbnail { get; set; }public IRandomAccessStreamReference Thumbnail { get; set; }Public ReadWrite Property Thumbnail As IRandomAccessStreamReferencepublic IRandomAccessStreamReference Thumbnail { get; set; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

We recommend that any time you create a DataPackage that contains images, you also assign a thumbnail image. Doing so gives target apps the opportunity to display a visual representation of the images being shared to the user while the share operation completes.

The minimum recommended size is 80x80. The maximum size is 240x160. These sizes are in device-independent pixels, so if the system plateau setting is other than 1.0, appropriate multiplier should be used. For example, minimum recommended size for 1.4 plateau would be 801.4x801.4=112x112 physical pixels. If you're writing a target app, remember that while we recommend a minimum and maximum size, there is no enforcement of these sizes. Your app should have code to handle thumbnails that are an unexpected sizeā€”such as to scale them up or down as needed. Take care, however, not to alter the aspect ratio of the image.

You can use any data format (JPG, GIF, and so on) for a thumbnail. You also have the option of loading the thumbnail from the disk, or creating it on the fly.

Examples

This example shows how you can add a thumbnail image to a DataPackage when sharing an image with a target app.

void DataRequested(DataTransferManager sender, DataRequestedEventArgs e)
{
    DataRequestDeferral deferral = e.Request.GetDeferral();
    e.Request.Data.Properties.Title = "Hello World!";
    e.Request.Data.Properties.Description = "This example shows how to share files and images.";
    if (this.dataPackageThumbnail != null)
    {
        e.Request.Data.Properties.Thumbnail = this.dataPackageThumbnail;
    }
    e.Request.Data.SetBitmap(imageStreamRef);
    deferral.Complete();
}
function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareImageHandler);
}

function shareImageHandler(e) {
    var request = e.request;
    request.data.properties.title = "Share Image Example";
    request.data.properties.description = "A demonstration that shows how to share an image.";
    var deferral = request.getDeferral();
    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\smalllogo.png").then(function (thumbnailFile) {
        request.data.properties.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(thumbnailFile);
        return Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\logo.png");
    }).done(function (imageFile) {
        request.data.setBitmap(Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(imageFile));
        deferral.complete();
    }, function (err) {
        request.failWithDisplayText(err);
    });
}

Title Title Title Title

Gets or sets the text that displays as a title for the contents of the DataPackage object.

public string Title { get; set; }public string Title { get; set; }Public ReadWrite Property Title As stringpublic string Title { get; set; }
Value
string string string string

The text that displays as a title for the contents of the DataPackage object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Setting this property is mandatory. Without it, any share operations involving the DataPackage will fail.

Examples

This example shows how you can set the title for the content in a DataPackage

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

Methods

Clear() Clear() Clear() Clear()

Removes all items from the property set.

public void Clear()public void Clear()Public Function Clear() As voidpublic void Clear()
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use this method in situations where you want to remove all of the properties in a DataPackagePropertySet at the same time.

First() First() First() First()

Returns an iterator to enumerate the items in the property set.

public IIterator<IKeyValuePair<string, object>> First()public IIterator<IKeyValuePair<string, object>> First()Public Function First() As IIterator( Of IKeyValuePairstring, object )public IIterator<IKeyValuePair<string, object>> First()
Returns

The first item in the DataPackage object.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

For more info, see IIterable<T>.

GetView() GetView() GetView() GetView()

Gets an immutable view of the property set.

public IMapView<string, object> GetView()public IMapView<string, object> GetView()Public Function GetView() As IMapView( Of string, object )public IMapView<string, object> GetView()
Returns

The immutable view.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Returns a DataPackagePropertySetView object, which is an immutable view of the DataPackagePropertySet object. For more info, see IMap<K, V>.

HasKey(String) HasKey(String) HasKey(String) HasKey(String)

Indicates whether the DataPackagePropertySet object contains a specific property.

public bool HasKey(String key)public bool HasKey(String key)Public Function HasKey(key As String) As boolpublic bool HasKey(String key)
Parameters
key
System.String System.String System.String System.String

The key.

Returns
bool bool bool bool

True if the property set has an item with the specified key; otherwise false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

With the DataPackagePropertySet class, use HasKey as a way to see whether the object contains a specific property. This is useful in situations where your app requires a custom property that the DataPackagePropertySet object doesn't directly support. For more info, see IMapView<K, V>.

Insert(String, Object) Insert(String, Object) Insert(String, Object) Insert(String, Object)

Adds a property to the DataPackagePropertySet object.

public bool Insert(String key, Object value)public bool Insert(String key, Object value)Public Function Insert(key As String, value As Object) As boolpublic bool Insert(String key, Object value)
Parameters
key
System.String System.String System.String System.String

The key to insert.

value
System.Object System.Object System.Object System.Object

The value to insert.

Returns
bool bool bool bool

True if the method replaced a value that already existed for the key; false if this is a new key.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use this method if your app needs to add a custom property to the DataPackagePropertySet object. A custom property is any property that you can't define by using an existing property of the object. For example, Title is a property that the object supports directly, but if you wanted a subtitle property, you would need to use Insert to add it.

For more info, see IMapView<K, V>.

Lookup(String) Lookup(String) Lookup(String) Lookup(String)

Retrieves the value of a specific property.

public object Lookup(String key)public object Lookup(String key)Public Function Lookup(key As String) As objectpublic object Lookup(String key)
Parameters
key
System.String System.String System.String System.String

The key.

Returns
object object object object

The value, if an item with the specified key exists. Use the HasKey method to determine whether the key exists.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

With the LookUp method, you specify the name of the property that you want. This name can be a property that the object supports directly, such as title, or a custom property defined by the source app.

For more info, see IMapView<K, V>.

Remove(String) Remove(String) Remove(String) Remove(String)

Removes an item from the property set.

public void Remove(String key)public void Remove(String key)Public Function Remove(key As String) As voidpublic void Remove(String key)
Parameters
key
System.String System.String System.String System.String

The key.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use Remove if you need to delete a property from the DataPackagePropertySet object.

For more info, see IMapView<K, V>.

For the C# and Microsoft Visual Basic version of the Remove(String) method, see Remove(String).