Please see the article on docs.microsoft.com for the latest documentation.

Please see the article on docs.microsoft.com for the latest documentation.

Please see the article on docs.microsoft.com for the latest documentation.

Please see the article on docs.microsoft.com for the latest documentation.

1. Are you using the Notifications library to construct your tile notifications?
   1. If not, are you XML-escaping content and constructing valid XML?
2. Are you trimming lengthy text strings, so you don't break the 5 KB payload restriction?
3. Are you using images in your tile notification?
   1. Ensure that the path to your images is valid
   2. If they are HTTP images, are the images less than 200 KB in size?
4. Did you include a binding for each tile size you support?
5. Did you accidently turn off the Live Tile in Start?

Payload larger than 5 KB

Remote HTTP image larger than 200 KB

Invalid XML payload

Include bindings for each tile size you support

Ensure the Live Tile isn't turned off

• caption: 63 characters
• body: 50 characters
• base: 46 characters
• subtitle: 37 characters
• title: 34 characters
• subheader: 26 characters
• header: 19 characters

• caption: 134 characters
• body: 107 characters
• base: 100 characters
• subtitle: 80 characters
• title: 73 characters
• subheader: 56 characters
• header: 41 characters

• caption: 82 characters
• body: 65 characters
• base: 60 characters
• subtitle: 49 characters
• title: 44 characters
• subheader: 34 characters
• header: 25 characters

• caption: 30 characters
• body: 24 characters
• base: 22 characters
• subtitle: 18 characters
• title: 16 characters
• subheader: 12 characters
• header: 9 characters

Limits on lines of text

• caption: 10 lines (11 without branding)
• body/base: 8 lines (9 without branding)
• subtitle: 6 lines (7 without branding)
• title: 5 lines (6 without branding)
• subheader: 3 lines (4 without branding)
• header: 2 lines (3 without branding)

• caption: 13 lines (15 without branding)
• body/base: 11 lines (12 without branding)
• subtitle: 8 lines (9 without branding)
• title: 7 lines (regardless of branding)
• subheader: 5 lines (regardless of branding)
• header: 3 lines (4 without branding)

• caption: 5 lines
• body/base: 4 lines
• subtitle: 3 lines
• title: 3 lines
• subheader: 2 lines
• header: 1 line

Use baseUri to reduce size of image URL's

<tile>
  <visual displayName="Seattle" baseUri="Assets/Apps/Weather/">

    <binding template="TileMedium" branding="name" hint-overlay="30">
      <image src="Mostly Cloudy-Background.jpg" placement="background"/>
      <group>
        <subgroup>
          <text hint-align="center">Mon</text>
          <image src="Mostly Cloudy.png" hint-removeMargin="true"/>
          <text hint-align="center">63°</text>
          <text hint-style="captionSubtle" hint-align="center">42°</text>
        </subgroup>
        <subgroup>
          <text hint-align="center">Tue</text>
          <image src="Cloudy.png" hint-removeMargin="true"/>
          <text hint-align="center">57°</text>
          <text hint-style="captionSubtle" hint-align="center">38°</text>
        </subgroup>
      </group>
    </binding>

  </visual>
</tile>

TileContent content = new TileContent()
{
    Visual = new TileVisual()
    {
        BaseUri = new Uri("Assets/Apps/Weather", UriKind.Relative),

        TileMedium = new TileBinding()
        {
            DisplayName = "Seattle",
            Branding = TileBranding.Name,
            Content = new TileBindingContentAdaptive()
            {
                Children =
                {
                    new AdaptiveGroup()
                    {
                        Children =
                        {
                            CreateSubgroup("Mon", "Mostly Cloudy.png", "63°", "42°"),
                            CreateSubgroup("Tue", "Cloudy.png", "57°", "38°")
                        }
                    }
                }
            }
        }
    }
};

...
private static AdaptiveSubgroup CreateSubgroup(string day, string image, string highTemp, string lowTemp)
{
    return new AdaptiveSubgroup()
    {
        Children =
        {
            new AdaptiveText()
            {
                Text = day,
                HintAlign = AdaptiveTextAlign.Center
            },
            new AdaptiveImage()
            {
                Source = image,
                HintRemoveMargin = true
            },
            new AdaptiveText()
            {
                Text = highTemp,
                HintAlign = AdaptiveTextAlign.Center
            },
            new AdaptiveText()
            {
                Text = lowTemp,
                HintAlign = AdaptiveTextAlign.Center,
                HintStyle = AdaptiveTextStyle.CaptionSubtle
            }
        }
    };
}

Don't specify attributes if you're using the default value

<binding template="TileMedium">
  <text hint-style="caption"  hint-wrap="false">Snowboarding with Mark</text>
  <text hint-style="captionSubtle" hint-wrap="true">Fri: 9:00 AM</text>
</binding>

Resources

• Tiles, badges, and notifications on MSDN
• Adaptive Tile Documentation
• Quickstart: Sending a local tile notification

Quick Summary

If you are already familiar with sending scheduled Toast notifications, you need to do two things, (1) use the "alarm" scenario on the Toast XML content, and (2) ensure you have at least one button on your Toast, as seen below. If you're not familiar with scheduled Toasts, please read this entire quickstart.

ToastContent toastContent = new ToastContent()
{
    Scenario = ToastScenario.Alarm,
    Visual = new ToastVisual() { ... },
    Actions = new ToastActionsCustom() { ... }
};

  
    ...
  

  
    ...
  

1. Install UWP Community Toolkit NuGet package

In order to create notifications via code, we strongly recommend using the UWP Community Toolkit Notifications library, which provides an object model for the notification XML content. You could manually construct the notification XML, but that is error-prone and messy. The Notifications library inside UWP Community Toolkit is built and maintained by the team that owns notifications at Microsoft.

Install Microsoft.Toolkit.Uwp.Notifications from NuGet (we're using version 1.0.0 in this documentation).

2. Add namespace declarations

Windows.UI.Notifications includes the Tile and Toast API's.

using Microsoft.Toolkit.Uwp.Notifications;
using Windows.UI.Notifications;

3. Construct the notification and specify scenario "alarm"

The Toast notification content includes text and images, and also buttons and inputs. Please see Quickstart: Sending a local toast notification and handling activations to see a full code snippet.

To make your Toast behave like an alarm (continuous looping audio, pops full screen on Mobile), set the Scenario to Alarm as seen below. And also ensure that you have at least one button on your Toast, or else it will not be displayed as an alarm.

ToastContent toastContent = new ToastContent()
{
    Scenario = ToastScenario.Alarm,
    Visual = new ToastVisual()
    {
        ... (omitted)
    },
    Actions = new ToastActionsCustom()
    {
        Inputs = { ... }
        Buttons =
        {
            ... (omitted)
        }
    }
};

4. Schedule the alarm to appear at a certain time

In order to make your Toast (alarm) appear at a specific time, you will need to use a scheduled Toast notification. This is essentially just a Toast notification with a delivery time.

You will construct a ScheduledToastNotification rather than a normal ToastNotification, and then you will call AddToSchedule rather than Show to schedule the notification for a future time.

DateTime alarmTime = DateTime.Now.AddMinutes(1);

// Only schedule notifications in the future
// Adding a scheduled notification with a time in the past
// will throw an exception.
if (alarmTime > DateTime.Now.AddSeconds(5))
{
    // Generate the toast content (from previous steps)
    ToastContent toastContent = GenerateToastContent();

    // Create the scheduled notification
    var scheduledNotif = new ScheduledToastNotification(
        toastContent.GetXml(), // Content of the toast
        alarmTime // Time we want the toast to appear at
        );

    // And add it to the schedule
    ToastNotificationManager.CreateToastNotifier().AddToSchedule(scheduledNotif);
}

Ensure your alarm will wake the phone from sleep

In order for your scheduled Toast to show exactly at the time you specified, you need to request access to background execution. Otherwise, while the phone is in sleep mode (screen off), your Toast may be delayed for an unknown amount of time (typically 30 seconds, sometimes longer), since the phone is conserving power.

Simply call RequestAccessAsync at some point in your app (like inside your App.xaml.cs). This only needs to be called once after your app is installed, but there is no harm in calling it multiple times.

await BackgroundExecutionManager.RequestAccessAsync();

Remove a scheduled alarm

If a user deletes or cancels their alarm, you will need to remove the ScheduledToastNotification that you scheduled.

Simply get a list of the currently scheduled Toast notifications from GetScheduledToastNotifications, find the notification that you want to remove, and call RemoveFromSchedule.

Note that if the alarm has already appeared, it will NOT appear in the scheduled notifications list. Instead, you can remove an alarm that has already appeared by using ToastNotificationManager.History.Remove, where you can remove a Toast by its Tag and/or Group.

var notifier = ToastNotificationManager.CreateToastNotifier();

// Get all scheduled notifications
var scheduled = notifier.GetScheduledToastNotifications();

// Find the one we want to remove
var toRemove = scheduled.FirstOrDefault(i => i.Id.Equals("userAlarm01"));

// And remove it
notifier.RemoveFromSchedule(toRemove);

Scheduling recurring alarms

The scheduled Toast API's do not have any recurrence options built in. That means you will have to use periodic background tasks to re-schedule your repeating alarms.

Here is a basic algorithm that you should use to continuously schedule your alarms.

1. Schedule your alarms up to 5 days in advance
2. Configure a TimeTrigger background task that runs every 24 hours
3. Have that background task re-schedule the alarms up to 5 days in advance

The code snippet below registers a background task that runs every 24 hours, and when the task triggers, re-schedules all the alarms. See the full code sample on GitHub for more details.

Note that we are using the Single Process Model for background tasks, which is only supported in builds 14393 or newer.

private void RegisterPeriodicBackgroundTask()
{
    if (!BackgroundTaskRegistration.AllTasks.Any(i => i.Value.Name.Equals("DailyTask")))
    {
        var builder = new BackgroundTaskBuilder()
        {
            Name = "DailyTask"
        };

        builder.SetTrigger(new TimeTrigger(24 * 60, false)); // Every 24 hours

        builder.Register();

    }
}

protected override async void OnBackgroundActivated(BackgroundActivatedEventArgs args)
{
    var deferral = args.TaskInstance.GetDeferral();

    if (args.TaskInstance.Task.Name.Equals("DailyTask"))
    {
        // Re-schedule the notifications
        await DataModel.LoadAsync();
        DataModel.EnsureAllScheduled();
    }

    deferral.Complete();
}

Resources

• Full code sample on GitHub
• Tiles, badges, and notifications on MSDN
• Interactive Toast Documentation

Why does it break?

• be able to register with the notification platform and;
• call WinRT APIs to send toast.

• A registration with notification platform requires an app identity, but win32 apps don’t really have modern app identities. This problem is solved by by allowing win32 apps to provide us with a "fake" app identity – through creating a desktop shortcut.
• The app will then need to call the method overload that takes this manually created application id to indicate which identity is trying to send this notification, as shown:

  ToastNotificationManager.CreateToastNotifier(appId).Show(toast);

• The shortcut creation will be skipped for the converted Store app during app deployment because the deployment path is different, however;
• The app will still call the same overload mentioned above to pass in the fake app id that the OS can no longer resolve, since the shortcut is not there, thus results in unresolved string.

How to fix it?

ToastNotificationManager.CreateToastNotifier().Show(toast);

Why didn't we fix this for you?

What does this mean?

• The NotificationsExtensions NuGet package is being deprecated. Please switch to the Microsoft.Toolkit.Uwp.Notifications NuGet package for all future development.
• The NotificationsExtensions GitHub repo is being deprecated. The code has been transitioned into the UWP Community Toolkit GitHub, where all future improvements will be made. Please submit any issues or pull requests on that new repo.

Migrating to the new library

New NuGet package

New namespace

using Microsoft.Toolkit.Uwp.Notifications;

using NotificationsExtensions;
using NotificationsExtensions.Tiles;
using NotificationsExtensions.Toasts;

Breaking changes before version 14332.0.0

Breaking changes post-14332.0.0

ToastVisual visual = new ToastVisual()
{
    BindingGeneric = new ToastBindingGeneric()
    {
        Children =
        {
            new AdaptiveText()
            {
                Text = title
            },
 
            new AdaptiveText()
            {
                Text = content
            },
 
            new AdaptiveImage()
            {
                Source = image
            }
        },
 
        AppLogoOverride = new ToastGenericAppLogo()
        {
            Source = logo,
            HintCrop = ToastGenericAppLogoCrop.Circle
        }
    }
};

ToastVisual visual = new ToastVisual()
{
    TitleText = new ToastText()
    {
        Text = title
    },

    BodyTextLine1 = new ToastText()
    {
        Text = content
    },

    InlineImages =
    {
        new ToastImage()
        {
            Source = image
        }
    },

    AppLogoOverride = new ToastAppLogo()
    {
        Source = logo,
        Crop = ToastImageCrop.Circle
    }
};

Please see the article on docs.microsoft.com for the latest documentation.