Share via

How to send a scheduled local Tile update for Windows Phone 8

  • Article

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic introduces you to the steps you take to update the background image of an app Tile using ShellTileSchedule. You also can use ShellTileSchedule to update secondary Tiles. For more info about Tiles, see Tiles for Windows Phone 8. You also can download the complete Shell Tile Schedule Sample.

Tip

The background image for the front of the Tile is the only property that you can update using ShellTileSchedule.

This topic contains the following sections.

Setting up a Tile schedule

You can use ShellTileSchedule to set up a one-time schedule or a recurring schedule to update the background image of the Tile. The schedule will continue to run even if your app is not active. You also can use ShellTileSchedule to stop any schedule running for your app. Apps should store their settings for ShellTileSchedule and start the schedule each time the app starts because failures in the schedule, even when the app is no longer running, can cancel out a schedule.

The ShellTileSchedule sample is a simple program with four buttons that initiate the corresponding following actions.

  • Update a Tile once.

  • Create a schedule to update a Tile indefinitely.

  • Create a schedule to update a Tile for a specific number of times.

  • Stop any schedule that is running.

Note

Pin the Tile to the Start screen to test updates.

To create the app UI

  1. Create a new Windows Phone app.

  2. On MainPage.xaml, replace the Grid named ContentPanel with the following code. This creates the four buttons for the UI.

            <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <Button Content="Start One Time Schedule" Height="72" HorizontalAlignment="Center" Margin="38,42,38,0" Name="buttonOneTime" VerticalAlignment="Top" Width="400" Click="buttonOneTime_Click" />
            <Button Content="Start Indefinite Schedule" Height="72" HorizontalAlignment="Center"  Margin="38,120,38,0" Name="buttonIndefinite" VerticalAlignment="Top" Width="400" Click="buttonIndefinite_Click" />
            <Button Content="Start Defined Count Schedule" Height="72" HorizontalAlignment="Center"  Margin="38,198,38,0" Name="buttonDefined" VerticalAlignment="Top" Width="400"  Click="buttonDefined_Click"/>
            <Button Content="Stop Schedule" Height="72" HorizontalAlignment="Center" Margin="38,276,38,0" Name="buttonStop" VerticalAlignment="Top" Width="400" Click="buttonStop_Click" />
        </Grid>

To create a Tile schedule

  1. Add a using directive to the top of the MainPage.xaml.cs file and provide the name of the namespace that includes ShellTileSchedule.

    using Microsoft.Phone.Shell;

  2. Declare and initialize your variables for the schedule and status.

    
public partial class MainPage : PhoneApplicationPage
{
    ShellTileSchedule SampleTileSchedule = new ShellTileSchedule();
    bool TileScheduleRunning = false;

  3. Add the code for a one-time update.

    private void buttonOneTime_Click(object sender, RoutedEventArgs e)
{
    // Update will happen one time.
    SampleTileSchedule.Recurrence = UpdateRecurrence.Onetime;

    // Start the update schedule now. 
    SampleTileSchedule.StartTime = DateTime.Now;

    SampleTileSchedule.RemoteImageUri = new Uri(@"http://www.weather.gov/forecasts/graphical/images/conus/MaxT1_conus.png");
    SampleTileSchedule.Start();
    TileScheduleRunning = true;
}

  4. Add code to set up a schedule that will run indefinitely. Remember that if the schedule fails too many times, it will be canceled.

    private void buttonIndefinite_Click(object sender, RoutedEventArgs e)
{
    // Updates will happen on a fixed interval. 
    SampleTileSchedule.Recurrence = UpdateRecurrence.Interval;

    // Updates will happen every hour.  Because MaxUpdateCount is not set, the schedule will run indefinitely.
    SampleTileSchedule.Interval = UpdateInterval.EveryHour;

    SampleTileSchedule.RemoteImageUri = new Uri(@"http://www.weather.gov/forecasts/graphical/images/conus/MaxT1_conus.png");
    SampleTileSchedule.Start();
    TileScheduleRunning = true;
}

  5. Add code to set up a schedule that will update the Tile a finite number of times. Again, if the schedule fails too many times, it will be canceled.

    private void buttonDefined_Click(object sender, RoutedEventArgs e)
{
    // Updates will happen on a fixed interval.
    SampleTileSchedule.Recurrence = UpdateRecurrence.Interval;

    // Updates will happen every hour.
    SampleTileSchedule.Interval = UpdateInterval.EveryHour;

    // Do a maximum of 50 updates and then stop.
    SampleTileSchedule.MaxUpdateCount = 50;

    SampleTileSchedule.RemoteImageUri = new Uri(@"http://www.weather.gov/forecasts/graphical/images/conus/MaxT1_conus.png");
    SampleTileSchedule.Start();
    TileScheduleRunning = true;
}

  6. Add code to stop any running schedule. You attach to a schedule by starting it.

    private void buttonStop_Click(object sender, RoutedEventArgs e)
{
    // Attach to a shell schedule by starting it.
    if (!TileScheduleRunning)
    {
        buttonIndefinite_Click(sender, e);
    }

    SampleTileSchedule.Stop();
    TileScheduleRunning = false;
}

Debugging an update schedule can be challenging. To conserve power, the updates are batched, so it may take up to an hour or so to see an updated image. Updates don’t occur when the device is locked, because the user wouldn’t see the updates.

To run and debug your app

  1. Run the app by selecting the Debug | Start Debugging menu command.

  2. When the emulator initializes and your program is running, press the Start button on the emulator to go to the Start screen. Navigate to the App list and find your app. Tap and hold the app name, and then select pin to start from the context menu. The app Tile is pinned to Start.

  3. Press the Back button to return to your app. Tap one of the buttons on the app to start a schedule.

  4. Return to the Start screen. Wait for the schedule to run to see the result. Remember that this may take up to an hour because the updates are batched.

Scheduling secondary Tiles

Although this sample doesn’t have secondary Tiles, you can set up a schedule for a secondary Tile by passing the Tile information to the ShellTileSchedule constructor. The following code example demonstrates how to set up a schedule for each existing Tile.

foreach (ShellTile TileToSchedule in ShellTile.ActiveTiles)
{
    ShellTileSchedule mySchedule = new ShellTileSchedule(TileToSchedule);
    mySchedule.Interval = UpdateInterval.EveryHour;
    mySchedule.Recurrence = UpdateRecurrence.Interval;
    mySchedule.RemoteImageUri = imageURI;
    mySchedule.Start();
}

See Also

Reference

ShellTileSchedule

Other Resources

Tiles for Windows Phone 8