DataPackagePropertySet DataPackagePropertySet DataPackagePropertySet DataPackagePropertySet Class

Definition

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

public : sealed class DataPackagePropertySet : IDataPackagePropertySet, IDataPackagePropertySet2, IDataPackagePropertySet3, IIterable<IKeyValuePair<Platform::String, Platform::Object>>, IMap<Platform::String, Platform::Object>
public sealed class DataPackagePropertySet : IDataPackagePropertySet, IDataPackagePropertySet2, IDataPackagePropertySet3, IEnumerable<KeyValuePair<String, Object>>, IDictionary<String, Object>
Public NotInheritable Class DataPackagePropertySet Implements IDataPackagePropertySet, IDataPackagePropertySet2, IDataPackagePropertySet3, IEnumerable<KeyValuePair<String, Object>>, IDictionary<String, Object>
// This class does not provide a public constructor.
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 method or one of the Add methods. Target apps can access specific properties through the Lookup 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 Uri
var uri = dataPackagePropertySet.applicationListingUri;
dataPackagePropertySet.applicationListingUri = uri;
Value
Uri Uri Uri Uri

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

ApplicationName ApplicationName ApplicationName ApplicationName

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

public : Platform::String ApplicationName { get; set; }
public string ApplicationName { get; set; }
Public ReadWrite Property ApplicationName As string
var string = dataPackagePropertySet.applicationName;
dataPackagePropertySet.applicationName = string;
Value
Platform::String string string string

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

ContentSourceApplicationLink ContentSourceApplicationLink ContentSourceApplicationLink ContentSourceApplicationLink

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 Uri
var uri = dataPackagePropertySet.contentSourceApplicationLink;
dataPackagePropertySet.contentSourceApplicationLink = uri;
Value
Uri Uri Uri Uri

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

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.

ContentSourceWebLink ContentSourceWebLink ContentSourceWebLink ContentSourceWebLink

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 Uri
var uri = dataPackagePropertySet.contentSourceWebLink;
dataPackagePropertySet.contentSourceWebLink = uri;
Value
Uri Uri Uri Uri

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

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 : Platform::String Description { get; set; }
public string Description { get; set; }
Public ReadWrite Property Description As string
var string = dataPackagePropertySet.description;
dataPackagePropertySet.description = string;
Value
Platform::String string string string

Text that describes the contents of the DataPackage.

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

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.

EnterpriseId EnterpriseId EnterpriseId EnterpriseId

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

public : Platform::String EnterpriseId { get; set; }
public string EnterpriseId { get; set; }
Public ReadWrite Property EnterpriseId As string
var string = dataPackagePropertySet.enterpriseId;
dataPackagePropertySet.enterpriseId = string;
Value
Platform::String string string string

The enterprise Id.

FileTypes FileTypes FileTypes FileTypes

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

public : IVector<Platform::String> FileTypes { get; }
public IList<string> FileTypes { get; }
Public ReadOnly Property FileTypes As IList<string>
var iList = dataPackagePropertySet.fileTypes;
Value
IVector<Platform::String> IList<string> IList<string> IList<string>

Contains the types of files stored in the DataPackage object.

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 method.

Item[TKey] Item[TKey] Item[TKey] Item[TKey]

Gets or sets the element with the specified key.

This member is not implemented in C++
TValue this[TKey key] { get; set; }
Property Item(key As TKey) As TValue
TValue this[TKey key] { get; set; }
Parameters
key
TKey TKey TKey TKey

The key of the element to get or set.

Value
TValue TValue TValue TValue

The element with the specified key.

Exceptions

key is null.

The property is retrieved and key is not found.

The property is set and the System.Collections.Generic.IDictionary`2 is read-only.

Keys Keys Keys Keys

Gets an System.Collections.Generic.ICollection`1 containing the keys of the System.Collections.Generic.IDictionary`2.

This member is not implemented in C++
ICollection<TKey> Keys { get; }
ReadOnly Property Keys As ICollection(Of TKey)
ICollection<TKey> Keys { get; }
Value

An System.Collections.Generic.ICollection`1 containing the keys of the object that implements System.Collections.Generic.IDictionary`2.

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 Color
var color = dataPackagePropertySet.logoBackgroundColor;
dataPackagePropertySet.logoBackgroundColor = color;
Value
Color Color Color Color

The color of the logo's background.

See Also

PackageFamilyName PackageFamilyName PackageFamilyName PackageFamilyName

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

public : Platform::String PackageFamilyName { get; set; }
public string PackageFamilyName { get; set; }
Public ReadWrite Property PackageFamilyName As string
var string = dataPackagePropertySet.packageFamilyName;
dataPackagePropertySet.packageFamilyName = string;
Value
Platform::String string string string

The package family name.

Size Size Size Size

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

public : unsigned int Size { get; }
This member is not implemented in C#
This member is not implemented in VB.Net
var uint = dataPackagePropertySet.size;
Value
unsigned int uint uint uint

The number of elements in the property set.

Square30x30Logo Square30x30Logo Square30x30Logo Square30x30Logo

Gets or sets the source app's logo.

public : IRandomAccessStreamReference Square30x30Logo { get; set; }
public IRandomAccessStreamReference Square30x30Logo { get; set; }
Public ReadWrite Property Square30x30Logo As IRandomAccessStreamReference
var iRandomAccessStreamReference = dataPackagePropertySet.square30x30Logo;
dataPackagePropertySet.square30x30Logo = iRandomAccessStreamReference;

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.

See Also

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 IRandomAccessStreamReference
var iRandomAccessStreamReference = dataPackagePropertySet.thumbnail;
dataPackagePropertySet.thumbnail = iRandomAccessStreamReference;

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);
    });
}

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.

Title Title Title Title

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

public : Platform::String Title { get; set; }
public string Title { get; set; }
Public ReadWrite Property Title As string
var string = dataPackagePropertySet.title;
dataPackagePropertySet.title = string;
Value
Platform::String string string string

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

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

Remarks

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

Values Values Values Values

Gets an System.Collections.Generic.ICollection`1 containing the values in the System.Collections.Generic.IDictionary`2.

This member is not implemented in C++
ICollection<TValue> Values { get; }
ReadOnly Property Values As ICollection(Of TValue)
ICollection<TValue> Values { get; }
Value

An System.Collections.Generic.ICollection`1 containing the values in the object that implements System.Collections.Generic.IDictionary`2.

Methods

Add(TKey, TValue) Add(TKey, TValue) Add(TKey, TValue) Add(TKey, TValue)

Adds an element with the provided key and value to the System.Collections.Generic.IDictionary`2.

This member is not implemented in C++
void Add(TKey key, TValue value)
Sub Add(key As TKey, value As TValue)
void Add(TKey key, TValue value)
Parameters
key
TKey TKey TKey TKey

The object to use as the key of the element to add.

value
TValue TValue TValue TValue

The object to use as the value of the element to add.

Exceptions

key is null.

An element with the same key already exists in the System.Collections.Generic.IDictionary`2.

The System.Collections.Generic.IDictionary`2 is read-only.

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

Removes all items from the property set.

public : void Clear()
This member is not implemented in C#
This member is not implemented in VB.Net
dataPackagePropertySet.clear();

Remarks

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

ContainsKey(TKey) ContainsKey(TKey) ContainsKey(TKey) ContainsKey(TKey)

Determines whether the System.Collections.Generic.IDictionary`2 contains an element with the specified key.

This member is not implemented in C++
bool ContainsKey(TKey key)
Function ContainsKey(key As TKey) As Boolean
bool ContainsKey(TKey key)
Parameters
key
TKey TKey TKey TKey

The key to locate in the System.Collections.Generic.IDictionary`2.

Returns

true if the System.Collections.Generic.IDictionary`2 contains an element with the key; otherwise, false.

Exceptions

key is null.

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

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

public : IIterator<IKeyValuePair<Platform::String, Platform::Object>> First()
This member is not implemented in C#
This member is not implemented in VB.Net
var iIterator = dataPackagePropertySet.first();
Returns
IIterator<IKeyValuePair<Platform::String, Platform::Object>> IIterator<KeyValuePair<string, object>> IIterator<KeyValuePair<string, object>> IIterator<KeyValuePair<string, object>>

The first item in the DataPackage object.

Remarks

For more info, see IIterable(IKeyValuePair).

GetEnumerator() GetEnumerator() GetEnumerator() GetEnumerator()

Returns an enumerator that iterates through the collection.

This member is not implemented in C++
IEnumerator<T> GetEnumerator()
Function GetEnumerator As IEnumerator(Of T)
IEnumerator<T> GetEnumerator()
Returns

An enumerator that can be used to iterate through the collection.

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

Gets an immutable view of the property set.

public : IMapView<Platform::String, Platform::Object> GetView()
This member is not implemented in C#
This member is not implemented in VB.Net
var iMapView = dataPackagePropertySet.getView();
Returns
IMapView<Platform::String, Platform::Object> IReadOnlyDictionary<string, object> IReadOnlyDictionary<string, object> IReadOnlyDictionary<string, object>

The immutable view.

Remarks

Returns a DataPackagePropertySetView object, which is an immutable view of the DataPackagePropertySet object. For more info, see IMap(String, Object).

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

Indicates whether the DataPackagePropertySet object contains a specific property.

public : Platform::Boolean HasKey(Platform::String key)
This member is not implemented in C#
This member is not implemented in VB.Net
var bool = dataPackagePropertySet.hasKey(key);
Parameters
key
Platform::String String String String

The key.

Returns
Platform::Boolean bool bool bool

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

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(String, Object).

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

Adds a property to the DataPackagePropertySet object.

public : Platform::Boolean Insert(Platform::String key, Platform::Object value)
This member is not implemented in C#
This member is not implemented in VB.Net
var bool = dataPackagePropertySet.insert(key, value);
Parameters
key
Platform::String String String String

The key to insert.

value
Platform::Object Object Object Object

The value to insert.

Returns
Platform::Boolean bool bool bool

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

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(String, Object).

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

Retrieves the value of a specific property.

public : Platform::Object Lookup(Platform::String key)
This member is not implemented in C#
This member is not implemented in VB.Net
var object = dataPackagePropertySet.lookup(key);
Parameters
key
Platform::String String String String

The key.

Returns
Platform::Object object object object

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

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(String, Object).

Remove(TKey) Remove(TKey) Remove(TKey) Remove(TKey)

Removes the element with the specified key from the System.Collections.Generic.IDictionary`2.

This member is not implemented in C++
bool Remove(TKey key)
Function Remove(key As TKey) As Boolean
bool Remove(TKey key)
Parameters
key
TKey TKey TKey TKey

The key of the element to remove.

Returns

true if the element is successfully removed; otherwise, false. This method also returns false if key was not found in the original System.Collections.Generic.IDictionary`2.

Exceptions

key is null.

The System.Collections.Generic.IDictionary`2 is read-only.

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

Removes an item from the property set.

public : void Remove(Platform::String key)
This member is not implemented in C#
This member is not implemented in VB.Net
dataPackagePropertySet.remove(key);
Parameters
key
Platform::String String String String

The key.

Remarks

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

For more info, see IMapView(String, Object).

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

TryGetValue(TKey, out TValue) TryGetValue(TKey, out TValue) TryGetValue(TKey, out TValue) TryGetValue(TKey, out TValue)

Gets the value associated with the specified key.

This member is not implemented in C++
bool TryGetValue(TKey key, out TValue value)
Function TryGetValue(key As TKey, ByRef value As TValue) As Boolean
bool TryGetValue(TKey key, out TValue value)
Parameters
key
TKey TKey TKey TKey

The key whose value to get.

value
TValue TValue TValue TValue

When this method returns, the value associated with the specified key, if the key is found; otherwise, the default value for the type of the value parameter. This parameter is passed uninitialized.

Returns

true if the object that implements System.Collections.Generic.IDictionary`2 contains an element with the specified key; otherwise, false.

Exceptions

key is null.