How to create, delete, and update Tiles for Windows Phone OS 7.1

Article
05/20/2016

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

This sample demonstrates how to update an app Tile using the ShellTile APIs. It also demonstrates how to create, delete, and update secondary Tiles.

Note

If you're looking for info about how to create and update Windows Phone 8 Tiles, see the corresponding Tile template topic: Flip Tile template for Windows Phone 8, Cycle Tile template for Windows Phone 8, or Iconic Tile template for Windows Phone 8.

The sample app contains three pages. The MainPage simply allows navigation to the two other pages. The ApplicationTile page allows you to update the properties of the Application Tile. All the properties are set at once. The SecondaryTile page allows you to create, update, and delete a secondary Tile. It allows you to set each property individually. It also demonstrates getting a value from the QueryString. If the user navigates to the SecondaryTile page from the MainPage, the DefaultTitle value will be FromMain. If the user navigates to the SecondaryTile page by tapping the secondary Tile, the DefaultTitle value will be FromTile.

Note

Note that ShellTile can be used to update the properties of an app Tile, but it cannot be used to create or delete an app Tile.

You can download the complete sample at Tile Sample.

Creating the project and laying out the UI

In this step, you create a new project and design the UI for the three pages in the app – MainPage, ApplicationTile, and SecondaryTile.

To create the UI layout

Create a new Windows Phone app and name it TileSample.
Use Microsoft Paint or another image-editing tool to create three Tile-sized image files to be used as background images. For simplicity’s sake, you can make them solid colors of red, blue, and green. Name them Red.jpg, Blue.jpg, and Green.jpg. You can also download the Tile Sample and use the images included there. Add the three image files to the project by selecting the TileSample project in Solution Explorer and selecting Project | Add Existing Item from the menu. Select the three image files and click Add. For each image file, set the Build Action property to Content.

Set the name of the app and page title in MainPage by replacing the TitlePanel with the following XAML code.

        <!--TitlePanel contains the name of the app and page title-->
        <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
            <TextBlock x:Name="ApplicationTitle" Text="Tile Sample" Style="{StaticResource PhoneTextNormalStyle}"/>
            <TextBlock x:Name="PageTitle" Text="Tiles" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}"/>
        </StackPanel>

The XAML code for the MainPage is below. It contains one text block and two buttons.

Control type	Control name	Control content
TextBlock	textBlockDescription	This sample demonstrates how to update Application Tiles. It also demonstrates how to create, update, and delete secondary Tiles.
Button	buttonChangeApplicationTile	Change the Application Tile.
Button	buttonChangeSecondaryTile	Change the secondary Tile.

Each button will handle the button\_Click event. To create the MainPage UI, replace **\ ```

The next step is to create the UI of ApplicationTile.xaml. To create the ApplicationTile UI, select the TileSample project name in the Solution Explorer, then select Project | Add New Item from the menu. Add a new Windows Phone Portrait Page and name it ApplicationTile.xaml. Click Add, and the ApplicationTile.xaml and ApplicationTile.xaml.cs files are created.

Set the name of the app and page title of the ApplicationTile page by replacing the TitlePanel with the following XAML code.

        <!--TitlePanel contains the name of the app and page title-->
        <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
            <TextBlock x:Name="ApplicationTitle" Text="Tile Sample" Style="{StaticResource PhoneTextNormalStyle}"/>
            <TextBlock x:Name="PageTitle" Text="Application Tile" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}" FontSize="64" />
        </StackPanel>

The XAML code for the ApplicationTile page is below. It contains one text block, a series of six text blocks and six text boxes, and a button to set the properties.

Control type	Control name	Control content
TextBlock	textBlockDescription	Sets Application Tile properties as a group. Leave text and image properties blank to clear the property. Set Count to 0 to clear the Count property.
TextBlock	textBlockTitle	Title
TextBox	textBoxTitle	<blank>
TextBlock	textBlockBackgroundImage	Background Image
TextBox	textBoxBackground	<blank>
TextBlock	textBlockCount	Count (1-99, 0=Clear)
TextBox	textBoxCount	<blank>
TextBlock	textBlockBackTitle	BackTitle
TextBox	textBoxBackTitle	<blank>
TextBlock	textBlockBackBackgroundImage	BackBackground Image
TextBox	textBoxBackBackGround	<blank>
TextBlock	textBlockBackContent	BackContent
TextBox	textBoxBackContent	<blank>
Button	buttonSetApplicationTile	Set Application Tile Properties

The **buttonSetApplicationTile** will handle the button\_Click event. Replace **\ ```

The final step of creating the UI is to add the SecondaryTile.xaml page. To create the SecondaryTile UI, select the TileSample project name in the Solution Explorer, then select Project | Add New Item from the menu. Add a new Windows Phone Portrait Page and name it SecondaryTile.xaml. Click Add, and the SecondaryTile.xaml and SecondaryTile.xaml.cs files are created.

Set the name of the app and page title of the SecondaryTile page by replacing the TitlePanel with the following XAML code.

        <!--TitlePanel contains the name of the app and page title-->
        <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
            <TextBlock x:Name="ApplicationTitle" Text="Tile Sample" Style="{StaticResource PhoneTextNormalStyle}"/>
            <TextBlock x:Name="PageTitle" Text="Secondary Tile" Margin="9,-7,0,0" Style="{StaticResource PhoneTextTitle1Style}" FontSize="64" />
        </StackPanel>

The XAML code for the SecondaryTile page is below. It contains one check box, one text block, and a series of six text boxes and six buttons.

Control type	Control name	Control content
CheckBox	checkBoxDisplaySecondaryTile	Display Secondary Tile
TextBlock	textBlockDescription	Sets properties of the secondary Tile individually.
TextBox	textBoxTitle	<blank>
Button	buttonTitle	Title
TextBox	textBoxBackGround	<blank>
Button	buttonBackGround	Background
TextBox	textBoxCount	<blank>
Button	buttonCount	Count
TextBox	textBoxBackTitle	<blank>
Button	buttonBackTitle	Back Title
TextBox	textBoxBackBackGround	<blank>
Button	buttonBackBackGround	Back Background
TextBox	textBoxBackContent	<blank>
Button	buttonBackContent	Back Content

The checkBoxDisplaySecondaryTile control will handle the checkboxDisplaySecondaryTile\_Checked and checkboxDisplaySecondaryTile\_Unchecked events. Each button will handle the button\_Click events. Replace **\ ```

Implementing MainPage

Implementing MainPage requires adding event handlers for the two buttons on MainPage.

To implement MainPage functionality

Add the following code to MainPage.xaml.cs. This code implements the event handlers for the button_Click event. When a button is clicked, the app navigates to the appropriate page. When navigating to the SecondaryTile page, the parameter DefaultTitle is set to FromMain so that the SecondaryTile page knows where navigation came from. Later, we’ll set DefaultTitle to FromTile when navigating to the SecondaryPage from a Tile.

        // Navigate to the page for modifying Application Tile properties.
        private void buttonChangeApplicationTile_Click(object sender, RoutedEventArgs e)
        {
            this.NavigationService.Navigate(new Uri("/ApplicationTile.xaml", UriKind.Relative));
        }


        // Navigate to the page for modifying secondary Tile properties. 
        // Pass a parameter that lets the SecondaryTile page know that it was navigated to from MainPage.
        // (DefaultTitle will equal 'FromTile' when the user navigates to the SecondaryTile page from a Tile.
        private void buttonChangeSecondaryTile_Click(object sender, RoutedEventArgs e)
        {
            this.NavigationService.Navigate(new Uri("/SecondaryTile.xaml?DefaultTitle=FromMain", UriKind.Relative));
        }

Implementing the ApplicationTile page

Implementing the ApplicationTile page will require adding an event handler for the buttonSetApplicationTile_Click event.

To implement the ApplicationTile page functionality

Add a using directive to the top of the ApplicationTile.xaml.cs file for the ShellTile namespace.
```
using Microsoft.Phone.Shell;
```

Add the following code to ApplicationTile.xaml.cs. This code will implement the event handler for the buttonSetApplicationTile_Click event. It will take the entered values in the text boxes and set all the properties of the Application Tile at once.

        // Set all the properties of the Application Tile.
        private void buttonSetApplicationTile_Click(object sender, RoutedEventArgs e)
        {
            int newCount = 0;

            // Application Tile is always the first Tile, even if it is not pinned to Start.
            ShellTile TileToFind = ShellTile.ActiveTiles.First();

            // Application should always be found
            if (TileToFind != null)
            {
                // if Count was not entered, then assume a value of 0
                if (textBoxCount.Text == "")
                {
                    // A value of '0' means do not display the Count.
                    newCount = 0;
                }
                // otherwise, get the numerical value for Count
                else
                {
                    newCount = int.Parse(textBoxCount.Text);
                }

                // Set the properties to update for the Application Tile.
                // Empty strings for the text values and URIs will result in the property being cleared.
                StandardTileData NewTileData = new StandardTileData
                {
                    Title = textBoxTitle.Text,
                    BackgroundImage = new Uri(textBoxBackgroundImage.Text, UriKind.Relative),
                    Count = newCount,
                    BackTitle = textBoxBackTitle.Text,
                    BackBackgroundImage = new Uri(textBoxBackBackgroundImage.Text, UriKind.Relative),
                    BackContent = textBoxBackContent.Text
                };

                // Update the Application Tile
                TileToFind.Update(NewTileData);
            }
        }

Implementing the SecondaryTile page

Implementing the SecondaryTile page requires setting the check box depending on the state of the secondary Tile, creating or deleting the check box depending on whether or not the check box is checked, and adding event handlers for each button.

To implement the SecondaryTile page functionality

Add a using directive to the top of the SecondaryTile.xaml.cs file for the ShellTile namespace.
```
using Microsoft.Phone.Shell;
```

Add the OnNavigatedTo event handler. Whenever we navigate to this page, we need to check to see whether the secondary Tile exists and set the check box appropriately. The default value for the Title is set here also, depending on the DefaultTitle set in the QueryString.

        // Event handler for when this page is navigated to. Looks to see
        // whether the Tile exists and set the check box appropriately.
        // Also fills in the default value for the Title, based on the
        // value passed in in the QueryString - either FromMain or FromTile.        
        protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
        {
            base.OnNavigatedTo(e);

            // See whether the Tile is pinned, and if so, make sure the check box for it is checked.
            // (User may have deleted it manually.)
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            checkBoxDisplaySecondaryTile.IsChecked = (TileToFind != null);

            // To demonstrate the use of the Navigation URI and query parameters, we set the default value
            // of the Title text box based on where we navigated from. If we navigated to this page
            // from the MainPage, the DefaultTitle parameter will be "FromMain". If we navigated here
            // when the secondary Tile was tapped, the parameter will be "FromTile".
            textBoxTitle.Text = this.NavigationContext.QueryString["DefaultTitle"];

        }

Add the following code for the checkBoxDisplaySecondaryTile_Checked event handler. This code checks to see whether a Tile with our designated ID already exists. If the Tile does not exist, the code creates a StandardTileData object and uses it to set the properties of the front and back of the Tile.

        // Event handler for when the check box is checked. Create a secondary Tile if it doesn't
        // already exist.
        private void checkBoxDisplaySecondaryTile_Checked(object sender, RoutedEventArgs e)
        {
            // Look to see whether the Tile already exists and if so, don't try to create it again.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // Create the Tile if we didn't find that it already exists.
            if (TileToFind == null)
            {
                // Create the Tile object and set some initial properties for the Tile.
                // The Count value of 12 shows the number 12 on the front of the Tile. Valid values are 1-99.
                // A Count value of 0 indicates that the Count should not be displayed.
                StandardTileData NewTileData = new StandardTileData
                {
                    BackgroundImage = new Uri("Red.jpg", UriKind.Relative),
                    Title = "Secondary Tile",
                    Count = 12,
                    BackTitle = "Back of Tile",
                    BackContent = "Welcome to the back of the Tile",
                    BackBackgroundImage = new Uri("Blue.jpg", UriKind.Relative)
                };

                // Create the Tile and pin it to Start. This will cause a navigation to Start and a deactivation of our app.
                ShellTile.Create(new Uri("/SecondaryTile.xaml?DefaultTitle=FromTile", UriKind.Relative), NewTileData);
            }

        }

Add the following code to the checkBoxDisplaySecondaryTile_Unchecked event handler. This code searches for the Tile with the ID that we gave it and then, if found, remove it from Start.

        // Event handler for when the check box is unchecked.  Delete the secondary Tile
        // if it exists.
        private void checkBoxDisplaySecondaryTile_Unchecked(object sender, RoutedEventArgs e)
        {
            // Find the Tile we want to delete.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then delete it.
            if (TileToFind != null)
            {
                TileToFind.Delete();
            }

        }

Add each of the button_Click event handlers. Each event handler looks for the Tile to update, gets the new value from the corresponding text box, and updates the Tile with the new value.

        // Handle the Title button clicked event by setting the front of Tile title.
        private void buttonSetTitle_Click(object sender, RoutedEventArgs e)
        {
            // Find the Tile we want to update.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then update the Title.
            if (TileToFind != null)
            {
                StandardTileData NewTileData = new StandardTileData
                {
                    Title = textBoxTitle.Text
                };

                TileToFind.Update(NewTileData);
            }

        }


        // Handle the Background Image button clicked event by setting the front of Tile background image.
        private void buttonSetBackgroundImage_Click(object sender, RoutedEventArgs e)
        {
            // Find the Tile we want to update.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then update the background image.
            if (TileToFind != null)
            {
                StandardTileData NewTileData = new StandardTileData
                {
                    BackgroundImage = new Uri(textBoxBackgroundImage.Text, UriKind.Relative)
                };

                TileToFind.Update(NewTileData);
            }

        }

        // Handle the Count button clicked event by setting the front of Tile count value.
        private void buttonSetCount_Click(object sender, RoutedEventArgs e)
        {
            int newCount = 0;

            // Find the Tile we want to update.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then update the count.
            if (TileToFind != null)
            {
                // if Count was not entered, then assume a value of 0.
                if (textBoxCount.Text == "")
                {
                    newCount = 0;
                }
                // Otherwise, get the numerical value for Count.
                else
                {
                    newCount = int.Parse(textBoxCount.Text);
                }

                StandardTileData NewTileData = new StandardTileData
                {
                    Count = newCount
                };

                TileToFind.Update(NewTileData);
            }

        }


        // Handle the Back Title button clicked event by setting the back of Tile title.
        private void buttonSetBackTitle_Click(object sender, RoutedEventArgs e)
        {
            // Find the Tile we want to update.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then update the title on the back of the Tile.
            if (TileToFind != null)
            {
                StandardTileData NewTileData = new StandardTileData
                {
                    BackTitle = textBoxBackTitle.Text
                };

                TileToFind.Update(NewTileData);
            }

        }


        // Handle the Back Background Image button clicked event by setting the back of Tile background image.
        private void buttonSetBackBackgroundImage_Click(object sender, RoutedEventArgs e)
        {
            // Find the Tile we want to update.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then update the background image on the back of the Tile.
            if (TileToFind != null)
            {
                StandardTileData NewTileData = new StandardTileData
                {
                    BackBackgroundImage = new Uri(textBoxBackBackgroundImage.Text, UriKind.Relative)
                };

                TileToFind.Update(NewTileData);
            }

        }

        // Handle the Back Content button clicked event by setting the back of Tile content.
        private void buttonSetBackContent_Click(object sender, RoutedEventArgs e)
        {
            // Find the Tile we want to update.
            ShellTile TileToFind = ShellTile.ActiveTiles.FirstOrDefault(x => x.NavigationUri.ToString().Contains("DefaultTitle=FromTile"));

            // If the Tile was found, then update the content on the back of the Tile.
            if (TileToFind != null)
            {
                StandardTileData NewTileData = new StandardTileData
                {
                    BackContent = textBoxBackContent.Text
                };

                TileToFind.Update(NewTileData);
            }

        }

You have now completed the code to create, delete, and update secondary Tiles.

To test your app:

Press F5 to start debugging your app. The app will start in the emulator.
Navigate to the Change Application Tile page. Set some properties for the Application Tile as shown in the following screenshot and click the Set Application Tile Properties button.
To see the result of the properties you set, navigate to Start by pressing the Start button on the phone emulator. Navigate to the Application List and find TileSample in the list. Tap and hold TileSample and then select pin to start. The emulator will navigate to Start and the Application Tile will be added. It should have the properties that you set in the step above.
Press the Back button on the phone emulator to navigate back to your app. By pressing the Back button, your debugging session will not end.
Press the Back button again to navigate to the app’s MainPage.
Navigate to the SecondaryTile page and check the check box to create the secondary Tile. The phone will automatically navigate to Start and the new Tile will appear.
Press the Back button on the phone emulator to navigate back to your app.
Enter a new value for the Title property and click the Set Title button.
Navigate back to Start by pressing the Start button on the phone emulator. The new Title property should be displayed.
Press the Back button again and try changing the other properties.
From Start, try tapping the secondary Tile. The TileSample app will start and navigate directly to the SecondaryTile page. The default value of Title will be FromTile.