Quickstart: Using the NotificationsExtensions library in your code (XAML)

Article
08/31/2015

Note Not using C#/VB/C++? See Quickstart: Using the NotificationsExtensions library in your code (HTML).

The NotificationsExtensions object model library allows you to supply tile, badge, and toast notification XML template contents without using the XML Document Object Model (DOM). It gives you a simpler, clearer, and more direct method of supplying notification content. When you use this library in Microsoft Visual Studio, you gain these advantages:

IntelliSense which lists the available tags and attributes as object properties, rather than having to consult the schema documentation for elements and structure.
A factory function through which you can create skeleton notifications that you can then fill in with your content.
A simplified way to include multiple tile sizes in your notification payload (a best practice!).
A helpful way to find and fill in text and image attributes, which are named to give you more information as to their intended use, size, or position in the template.

Note The NotificationsExtensions library is released under an Microsoft Limited Public License (MS-LPL). You may reuse the library in your Windows Store app or web service and customize it if necessary for your app.

Prerequisites

A working knowledge of tile and notification terms and concepts. For more information, see Tiles, Badges, and Notifications.
The ability to create a basic Windows Store app with C# or C++ Microsoft Visual Basic using Windows Runtime APIs. For more information, see Create your first Windows Store app using C# or Visual Basic.
A basic knowledge of XML will give you a better idea of what the NotificationsExtensions library is creating for you.

Instructions

1. Get the NotificationsExtensions library

The NotificationsExtensions library is included in several downloadable tile, toast, and notifications samples and can be copied from them for your own use. We'll use the main tiles and badges sample in this procedure.

Note NotificationsExtensions is a C# library, but can be included in and used with JavaScript, C#, C++, and Visual Basic projects.

Download the App tiles and badges sample from the Windows Dev Center.
Unzip the "App tiles and badges sample.zip" file to a folder of your choosing.
Go to the folder to which you unzipped the sample. Copy the NotificationsExtensions folder from the sample into your own project directory, as a sibling of your project's .sln file.

2. Include the library in your project

Launch Visual Studio and open your project.
In the Project Explorer, right-click the solution at the top of the tree.
Select Add then Existing Project.
Navigate to the NotificationsExtensions folder in your project and select the NotificationsExtensions.csproj file.
In each project within your solution, right-click References and select Add Reference.
In the Reference Manager, under Solution, select NotificationsExtensions and then click OK. At this point, NotificationsExtensions is ready to use.

Note If you don't want to include the full NotificationsExtensions project in your solution, you can build NotificationsExtensions as a stand-alone project and simply include the NotificationsExtensions.winmd as a reference in your project.

3. Include the library on your app server

You can also use NotificationsExtensions in your app server code if you are using ASP.NET to send push notifications to Windows Push Notification Services (WNS) or if you are implementing an ASP.NET service to handle requests for periodic tile or badge updates. The only caveat is that you must add the WINRT_NOT_PRESENT compilation build symbol in the NotificationsExtensions project properties.

Go to the directory in which you unzipped the sample. Open the sample folder and copy its NotificationsExtensions folder to a new location of your choosing.
Select the NotificationsExtensions.csproj file to open the project in Visual Studio.
From the Project menu, choose NotificationsExtensions Properties.
Change the Output type selection to "Class Library" to build a DLL file.
Also in the NotificationsExtensions properties, select the Build tab.
Under the General category, add "WINRT_NOT_PRESENT" in the Conditional compilation symbols box. If the box already contains other symbols, add a semi-colon as a separator before "WINRT_NOT_PRESENT".
Press F7 or use Build > Build Solution to build the project.
Copy the built NotificationsExtensions.dll file from your folder (under \NotificationsExtensions\bin\Debug\) to your app server code.

4. Use the library in your code

NotificationsExtensions can now be used as an object in your code. Its contains three members of note:

BadgeContent
TileContent
ToastContent

Each of those content types in turn contains members that represent the elements and attributes for each type.

The following example uses NotificationsExtensions to assign a value to a numeric badge, and then sends it to the tile.

using Windows.UI.Notifications;
using NotificationsExtensions.BadgeContent;

BadgeNumericNotificationContent badgeContent = new BadgeNumericNotificationContent((uint)85);
BadgeUpdateManager.CreateBadgeUpdaterForApplication().Update(badgeContent.CreateNotification());

using namespace Windows::UI::Notifications;
using namespace NotificationsExtensions::BadgeContent;

auto badgeContent = ref new BadgeNumericNotificationContent(85);
BadgeUpdateManager::CreateBadgeUpdaterForApplication()->Update(badgeContent->CreateNotification());

For comparison, the following example shows the same C# procedure without NotificationsExtensions, using the XML DOM.

using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

XmlDocument badgeXml = BadgeUpdateManager.GetTemplateContent(BadgeTemplateType.BadgeNumber);
XmlElement badgeElement = (XmlElement)badgeXml.SelectSingleNode("/badge");
badgeElement.SetAttribute("value", "85");

BadgeNotification badge = new BadgeNotification(badgeXml);
BadgeUpdateManager.CreateBadgeUpdaterForApplication().Update(badge);

The next example uses NotificationsExtensions to supply text in a tile notification. The first step uses the NotificationsExtensions TileContentFactory function to create an object based on a specific template. There is a separate create function for each template; simply attach the word "create" to the template name, such as "createTileWide310x150ImageAndText01".

The template-based object then provides IntelliSense to show the elements available in that template, as properties named according to their function, such as textHeading, textBodyWrap, textBody1, or textColumn1Row4. This tells you precisely which element you are assigning.

Once you've assigned values to the properties, you send the tile notification normally.

using Windows.UI.Notifications;
using NotificationsExtensions.TileContent;

ITileSquare150x150Text01 tileContent = TileContentFactory.CreateTileSquare150x150Text01();

tileContent.TextHeading.Text = "Hello!";
tileContent.TextBody1.Text = "One";
tileContent.TextBody2.Text = "Two";
tileContent.TextBody3.Text = "Three";

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileContent.CreateNotification());

using namespace Windows::UI::Notifications;
using namespace NotificationsExtensions::TileContent;

auto tileContent = TileContentFactory::CreateTileSquare150x150Text01();

tileContent->TextHeading->Text = "Hello!";
tileContent->TextBody1->Text = "One";
tileContent->TextBody2->Text = "Two";
tileContent->TextBody3->Text = "Three";

TileUpdateManager::CreateTileUpdaterForApplication()->Update(tileContent->CreateNotification());

This example uses NotificationsExtentions to assign text and an image to a notification. Like text, image elements are shown as properties named for their function in the template, such as imageMain and imageSmallColumn2Row2.

using Windows.UI.Notifications;
using NotificationsExtensions.TileContent;

ITileWide310x150ImageAndText01 tileContent = TileContentFactory.CreateTileWide310x150ImageAndText01();

tileContent.TextCaptionWrap.Text = "This tile notification uses ms-appx images";

tileContent.Image.Src = "ms-appx:///images/redWide.png";
tileContent.Image.Alt = "A red rectangle";

using namespace Windows::UI::Notifications;
using namespace NotificationsExtensions::TileContent;

auto tileContent = TileContentFactory::CreateTileWide310x150ImageAndText01();

tileContent->TextCaptionWrap->Text = "This tile notification uses ms-appx images";

tileContent->Image->Src = "ms-appx:///images/redWide.png";
tileContent->Image->Alt = "A red rectangle";

This example uses NotificationsExtensions to define a full tile notification. This illustrates one peculiarity of this library—the order in which you add template sizes to the payload matters.

A small template (square71x71—Windows Phone 8.1 only) can only be added to a medium template.
A medium template (square150x150) can only be added to a wide template.
A wide template can only be added to a large (square310x310—Windows only) template.

If you try to do it in a different order, you'll find that the necessary properties are not available.

using Windows.UI.Notifications;
using NotificationsExtensions.TileContent;
                        
ITileSquare310x310Text09 tileLargeContent = TileContentFactory.CreateTileSquare310x310Text09();

tileLargeContent.TextHeadingWrap.Text = "Lorem ipsum dolor sit amet, consectetur";
tileLargeContent.TextHeading1.Text = "Lorem ipsumo";
tileLargeContent.TextHeading2.Text = "Lorem ipsumo";
tileLargeContent.TextBody1.Text = "VivAmus tincidunt convallis urn";
tileLargeContent.TextBody2.Text = "VivAmus tincidunt convallis urn";

ITileWide310x150Text04 tileWideContent = TileContentFactory.CreateTileWide310x150Text04();
tileWideContent.TextBodyWrap.Text = "Lorem ipsum dolor sit amet, consectetur";

ITileSquare150x150Block tileMediumContent = TileContentFactory.CreateTileSquare150x150Block();
tileMediumContent.TextBlock.Text = "24";
tileMediumContent.TextSubBlock.Text = "Aliquam";
        
tileWideContent.Square150x150Content = tileMediumContent;
tileLargeContent.Wide310x150Content = tileWideContent;

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileLargeContent.CreateNotification());

using namespace Windows::UI::Notifications;
using namespace NotificationsExtensions::TileContent;
                        
auto tileLargeContent = TileContentFactory::CreateTileSquare310x310Text09();

tileLargeContent->TextHeadingWrap->Text = "Lorem ipsum dolor sit amet, consectetur";
tileLargeContent->TextHeading1->Text = "Lorem ipsumo";
tileLargeContent->TextHeading2->Text = "Lorem ipsumo";
tileLargeContent->TextBody1->Text = "VivAmus tincidunt convallis urn";
tileLargeContent->TextBody2->Text = "VivAmus tincidunt convallis urn";

auto tileWideContent = TileContentFactory::CreateTileWide310x150Text04();
tileWideContent->TextBodyWrap->Text = "Lorem ipsum dolor sit amet, consectetur";

auto tileMediumContent = TileContentFactory::CreateTileSquare150x150Block();
tileMediumContent->TextBlock->Text = "24";
tileMediumContent->TextSubBlock->Text = "Aliquam";

tileWideContent->Square150x150Content = tileMediumContent;
tileLargeContent->Wide310x150Content = tileWideContent;

TileUpdateManager::CreateTileUpdaterForApplication()->Update(tileLargeContent->CreateNotification());

This example uses NotificationsExtensions to supply content for a toast notification, including text, image, audio, duration, and launch parameters.

IToastImageAndText01 templateContent = ToastContentFactory.CreateToastImageAndText01();
                templateContent.TextBodyWrap.Text = "Body text that wraps";
                templateContent.Image.Src = TOAST_IMAGE_SRC;
                templateContent.Image.Alt = ALT_TEXT;                        
                        
                        
IToastNotificationContent toastContent = NotificationsExtensions.ToastContent.ToastContentFactory.CreateToastImageAndText01();

toastContent.TextBodyWrap.Text = "Lorem ipsum dolor sit amet";

toastContent.Image.Src = "ms-appx:///images/redWide.png";
toastContent.Image.Alt = "A red rectangle";

toastContent.Audio.Content = NotificationsExtensions.ToastContent.ToastAudioContent.LoopingAlarm;
toastContent.Audio.Loop = true;

toastContent.Duration = NotificationsExtensions.ToastContent.ToastDuration.Long;

toastContent.Launch = "{\"type\":\"toast\",\"param1\":\"12345\",\"param2\":\"67890\"}";

ToastNotification toast = toastContent.CreateNotification();
Windows.UI.Notifications.ToastNotificationManager.CreateToastNotifier().Show(toast);

IToastImageAndText01^ toastContent = NotificationsExtensions::ToastContent::ToastContentFactory::CreateToastImageAndText01();

toastContent->TextBodyWrap->Text = "Lorem ipsum dolor sit amet";

toastContent->Image->Src = "ms-appx:///images/redWide.png";
toastContent->Image->Alt = "A red rectangle";

toastContent->Audio->Content = NotificationsExtensions::ToastContent::ToastAudioContent::LoopingAlarm;
toastContent->Audio->Loop = true;

toastContent->Duration = NotificationsExtensions::ToastContent::ToastDuration::Long;

toastContent->Launch = "{\"type\":\"toast\",\"param1\":\"12345\",\"param2\":\"67890\"}";

auto toast = toastContent->CreateNotification();

Windows::UI::Notifications::ToastNotificationManager::CreateToastNotifier()->Show(toast);

Summary

This topic has shown you how to use NotificationsExtensions to simplify the creation of badge, tile, and toast notifications. This is a more straightforward way to populate a template than dealing directly with the XML DOM.