#Win8Dev Tutorial: Share Contract using DataTransferManager in WinRT apps

If you are a Windows 8 Store application and/or game developer, you may want to provide feature to share text, graphics, links or game score cards to Facebook, Twitter or Email. Windows 8 SDK provides those APIs to implement the feature in your application.

Today in this chapter of the Windows Store Tutorial series, we will discuss more about the API methods and how to integrate it in your application. Continue reading.

Introduction to Share Contract

You might already aware of the Charm Bar in Windows 8, which has 5 different options named “Search”, “Share”, “Start”, “Devices” and “Settings” from top to bottom placed at the right side of the screen. By default this panel is hidden but you can invoke it by placing your mouse pointer at the top right or bottom right corner of the screen. In this tutorial chapter, we will discuss about programmatically accessing the Share option of this Charm Bar.

The SDK provides a class named “DataTransferManager” which you can use to programmatically initiate an exchange of content with other application. The DataTransferManager.GetForCurrentView() method provides the handle of the object associated with current window.

You need to register the DataRequested event to handle the share operation when it starts and return you a DataPackage object. The other API method ShowShareUI() of DataTransferManager invokes the charm bar with share option selected by default.

Here is the code snippet of what you need to integrate:

// get the DataTransferManager object associated with current window

var dataTransferManager = DataTransferManager.GetForCurrentView();

// register event to handle the share operation when it starts

dataTransferManager.DataRequested -= OnDataRequested;

dataTransferManager.DataRequested += OnDataRequested;

// show the charm bar with Share option opened

DataTransferManager.ShowShareUI();

There are 6 different types of content you can share with the DataTransferManager object:

• Plain Text
• Link
• Formatted Content / HTML
• Files
• Single Image
• Custom Data Format

Data is shared through an object called the DataPackage. The DataRequested event passes the DataPackage object which you can use to set the properties and the below APIs provides you easy access to share content from your application:

public void SetText(string value);

public void SetUri(Uri value);

public void SetHtmlFormat(string value);

public void SetRtf(string value);

public void SetBitmap(RandomAccessStreamReference value);

public void SetStorageItems(IEnumerable<IStorageItem> value);

public void SetStorageItems(IEnumerable<IStorageItem> value, bool readOnly);

This is how you can share plain text, URL, formatted HTML content, RTF, image and other types of files. Now we can see a practical demonstration with few of the above contracts.

Integrating Share Contract

It is very easy to integrate the share contract in your Windows 8 Store application for your users. You can do this by calling the APIs from the DataRequested event implementation. So, let’s implement the DataRequested event. First we will need to populate the data package that comes as args.Request.Data. Once you populate the Title and Description properties, which generally show up in the Flyout charm bar when you click the Share item, you need to call the proper SDK API and that will list down the appropriate applications as shown below:

To implement the plain text sharing from Windows Store app, call the dataPackage.SetText() method with the string that you want to share, as shown in the below code snippet:

var dataPackage = args.Request.Data;

dataPackage.Properties.Title = "Plain Text Share Demo";

dataPackage.Properties.Description = "Sharing of Plain Text from Windows 8 Store app";

dataPackage.SetText("This demo shows you how to share plain text from Windows 8 Store app");

This will give you option to share the text as email to your contacts. If you have already the Mail application setup (Windows Store application), it will directly show you the compose window with the text auto populated with title that you specified, else it will ask you to create a new mail account to share.

In case you want to share a link from your application, call the SetUri() method and that will show you the People and Mail Windows Store application. So, using this you can share link to integrated Facebook or Twitter accounts. Here is the code snippet of the same:

var dataPackage = args.Request.Data;

dataPackage.Properties.Title = "Kunal-Chowdhury.com";

dataPackage.Properties.Description = "A Microsoft Technology blog about Windows Phone, 
                                      Silverlight, WPF, XAML and .NET";

dataPackage.SetUri(new Uri("http://www.kunal-chowdhury.com", UriKind.Absolute));

This is how the People application will launch with the URL that you want to share. The dropdown lists Facebook and Twitter accounts if authenticated.

Here is the screenshot of the Mail application with the shared link. You can see that it populates the title and short description of the link automatically in the applications.

Now let’s see how the formatted HTML content will look like when you share from your application. You need to call the SetHtmlFormat() method with proper HTML content passing it as parameter to HtmlFormatHelper.CreateHtmlFormat() method.

Here’s the code snippet of the same:

var dataPackage = args.Request.Data;

dataPackage.Properties.Title = "Kunal-Chowdhury.com";

dataPackage.Properties.Description = "A Microsoft Technology blog.";

dataPackage.SetHtmlFormat(HtmlFormatHelper.CreateHtmlFormat(
                          "<h1>Kunal-Chowdhury.com</h1><br/><br/>
                           A <a href='http://www.kunal-chowdhury.com'>blog</a> 
                           on Microsoft Technology"));

This will load the Windows 8 Store Mail application in the screen with the formatted HTML content inside the application/ Check out the below screenshot for details:

The email application will launch with the content only if you setup your mail account otherwise it will ask you to configure the Windows Store Mail application. Remember that, it will not list or invoke the desktop applications here.

End Note

I guess that the chapter was easy to understand about sharing content from your Windows 8 Store application. Like the above examples, you can share image or other files as attachment directly from your application. Try those individually using the SDK APIs mentioned above and let me know if any queries. I appreciate your valuable comments below.

Subscribe to my blog’s RSS Feed and Email Newsletter to get updates delivered to your inbox. I am available on Facebook, Twitter and Google+. Add me as friend to stay connected for any kind of discussions.