DataPackagePropertySet DataPackagePropertySet DataPackagePropertySet DataPackagePropertySet Class

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

Syntax

Declaration

public sealed class DataPackagePropertySetpublic sealed class DataPackagePropertySetPublic NotInheritable Class DataPackagePropertySet

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(System.String,System.Object) method or one of the Add methods. Target apps can access specific properties through the Lookup(System.String) or TryGetValue methods.

Collection member lists

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

Properties summary

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

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

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

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

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

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

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

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

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

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

Gets or sets the source app's logo.

Gets or sets a thumbnail image for the DataPackage.

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

Methods summary

Removes all items from the property set.

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

Gets an immutable view of the property set.

Indicates whether the DataPackagePropertySet object contains a specific property.

Adds a property to the DataPackagePropertySet object.

Retrieves the value of a specific property.

Removes an item from the property set.

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

    Property Value

    • 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 string ApplicationName { get; set; }public string ApplicationName { get; set; }Public ReadWrite Property ApplicationName As string

    Property Value

    • string
      string
      string
      string

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

  • 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 string

    Property Value

    • string
      string
      string
      string

      Text that describes the contents of the DataPackage.

    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 string

    Property Value

    • 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<string> FileTypes { get; }public IVector<string> FileTypes { get; }Public ReadOnly Property FileTypes As IVector<string>

    Property Value

    • 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(System.String,Windows.ApplicationModel.DataTransfer.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 Color

    Property Value

  • 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 string

    Property Value

    • 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 uint Size { get; }public uint Size { get; }Public ReadOnly Property Size As uint

    Property Value

    • uint
      uint
      uint
      uint

      The number of elements in the property set.

  • 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

    Property Value

    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 string

    Property Value

    • string
      string
      string
      string

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

    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 void

    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 )

    Returns

    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 )

    Returns

    • The immutable view.

    Remarks

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

  • HasKey(System.String)
    HasKey(System.String)
    HasKey(System.String)
    HasKey(System.String)

    Indicates whether the DataPackagePropertySet object contains a specific property.

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

    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.

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

    Adds a property to the DataPackagePropertySet object.

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

    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.

    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(System.String)
    Lookup(System.String)
    Lookup(System.String)
    Lookup(System.String)

    Retrieves the value of a specific property.

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

    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.

    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(System.String)
    Remove(System.String)
    Remove(System.String)
    Remove(System.String)

    Removes an item from the property set.

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

    Parameters

    • key
      System.String
      System.String
      System.String
      System.String

      The key.

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

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.ApplicationModel.DataTransfer.dll