Diary of a Windows developer

• Sep 11, 2012 in Windows 8

  How to create and debug a background task in Windows 8 – Part 1

  Finally, after many tries, I’ve been able to find which is the correct way to create, configure and debug a background task in Windows 8. Let’s make a little step backward: like in the Windows Phone world, Windows 8 apps can’t run in the background. In fact, they are automatically suspended after 10 seconds that the app is not in foreground anymore. To override this limitation, Windows 8 has introduced background tasks, that are operations that can be executed in background when a criteria is satisfied: a timer is expired, a push notification is received, the computer status is changed and so on.

  The concept should be familiar to Windows Phone developers: Windows Phone 7.5 has introduced the same way to support background operations. The biggest difference is that Windows 8 background tasks are more powerful: in Windows Phone there are only a few background tasks categories (mainly, based on timer events), while in Windows 8 you can create tasks that are executed when many different conditions are satisfied.

  The downside is that, in Windows 8, background tasks are not so easy to implement and debug, mainly because a dedicated Visual Studio template is missing (unlike in Windows Phone), so it’s a bit tricky to understand how they work.

  The first important thing to keep in mind is that a background task is a separate Visual Studio project, that is part of the same solution that contains the main application. So, the first step is to create a new project, by right clicking on the solution and choosing Add – New project. The template you’re going to use is Windows Runtime Component, inside the Windows Store category.

  

  It’s important to use this template because, in this case, the output type of the project will be automatically set to Windows Runtime Component (you can see it in the dropdown under the Output type library in the project’s properties). If you use another project’s type (like Class Library) the background task won’t work.

  

  Now let’s proceed to write some code: rename the class that is automatically created with the project to a more appropriate name (for example, NotificationTask) and change it so that it inherits from the IBackgroundTask interface.

  This interface will required you to implement the Run method, which is the one that is called when the background task is executed: it will contain all the logic needed to perform the background operations. In this example, I will create a simple background task that displays a toast notification. Here is the method that we use to send the notification, using one of the available templates:

  private void SendNotification(string text)
  {
      XmlDocument toastXml = ToastNotificationManager.GetTemplateContent(ToastTemplateType.ToastText01);
  
      XmlNodeList elements = toastXml.GetElementsByTagName("text");
      foreach (IXmlNode node in elements)
      {
          node.InnerText = text;
      }
  
      ToastNotification notification = new ToastNotification(toastXml);
      ToastNotificationManager.CreateToastNotifier().Show(notification);
  }

  Using the ToastNotificationManager we get the XML that identifies one of the available templates and we proceed to change the text node, **which contains the notification’s text. In the end, we create a new **ToastNotification object using the updated template and we shot it using again the ToastNotificationManager.

  In the Run method we’re simply going to call this method passing a fake text as parameter:

  public void Run(IBackgroundTaskInstance taskInstance)
  {
      SendNotification("This is a toast notification");
  }

  As you can see the Run method comes with a IBackgroundTaskInstance object, that contains all the information about the current task. This parameter is important especially if we’re going to write asynchronous code because, with the architecture we’ve just seen, the task will end before the asynchronous code is completed.

  For this reason, we should use a BackgroundTaskDeferral object, that we can get from the taskInstance parameter, as in the following example:

  public async void Run(IBackgroundTaskInstance taskInstance)
  {
      BackgroundTaskDeferral deferral = taskInstance.GetDeferral();
  
      //we launch an async operation using the async / await pattern    
      await CheckNewItems();
  
      deferral.Complete();
  }

  First, we get the BackgroundTaskDeferral object by calling the GetDeferral metohod of the taskInstance object. Then, we execute our asynchronous code (in the example, we call a fake method that checks if there are new items to download) and then, in the end, when everything is complete, we call the Complete method on the BackgroundTaskDeferral object.

  Show me some client love

  Ok, so far we’ve seen how to create the background task. But how we tell to the client (the real Windows 8 application) to use the background task? There are two steps: the first one is to declare the task in the manifest. Double click on the Package.appxmanifest, so that the visual editor shows up, go to the Declarations section and add a Background Tasks declaration: we’re going to set two important fields.

  • The first one is the background task’s type: in our example we’re going to use a timer background tasks, which can be executed periodically. You’ll simply have to check one of the available options.
  • The second one is the background task’s full entry point, which is the namespace plus the name of the class. Since in our example I’ve created a NotificationTask class inside a project called BackgroundTask.NotificationTask, the entry point will be BackgroundTask.NotificationTask.NotificationTask.

  

  We haven’t finished to edit the manifest yet: as you can see in the image, once we’ve set the background task a warning icon (the white cross over the red dot) appears in the Application UI tab. This happens because when you include a background task which type is Timer, Push notification or Control Channel you are forced to set which type of lock notification you’re going to use. This is required because these kind of background tasks are mainly used to support lock screen notifications.

  To do that, open the Application UI tab and:

  • Set in the Lock screen notifications option if you’re going to use display just a badge (the icon with a number) or you support also text (like, for example, the Calendar app, that shows the title of the next appointiment).
  • Include an icon to use as a badge for lock notifications. It should be an image file with resolution 24×24.

  The last thing to do is, in the Notifications section, set the option Toast capable to yes, since the background task we’ve created display toast notifications.

  

  It’s time to write some code… almost

  In the next post we’ll see how to register the background task in the code and how Visual Studio 2012 helps us in testing and debugging the background task.

• Aug 29, 2012 in Windows 8

  How to override the default color of a ProgressBar in a Windows 8 application

  So you’re doing Windows 8 development and, very likely, your app needs to display some data. Rarely this data is immediately available: maybe you need to download it, or you have to parse it before displaying it. Here comes in help the ProgressBar, so that the user is aware that something is loading and that he needs to wait until the operation is completed.

  By default, the ProgressBar automatically uses the accent color the user has selected for his Windows 8 installation: this isn’t always the best choice, because your application may use a background that doesn’t fit with the ProgressBar color.

  The first thing you would try to do, as a developer, is to change the Foreground or the Background property of the control, but you’ll notice that the trick doesn’t work: the color of the ProgressBar doesn’t change.

  This happens because the default ProgressBar color is defined in one of the default styles, so you have to override it to change it. To do this, simply add the following statement in the ApplicationResources defined in the App.xaml file:

  <ResourceDictionary.ThemeDictionaries>
      <ResourceDictionary x:Key="Default">
          <x:String x:Key="ProgressBarIndeterminateForegroundThemeBrush">White</x:String>
      </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>

  In this example, the ProgressBar is displayed with a white color: instead of writing the color’s name, you can also put the hexadecimal code of the color.

  Enjoy it!

• Aug 22, 2012 in SQLite and Windows 8

  SQLite for WinRT is now available on Visual Studio Gallery

  Thanks to Tim Heuer I’ve found that there’s an easier way to add SQLite to your Windows 8 application rather than the manual one described in my post. Now SQLite for WinRT is available as a Visual Studio extension, you can simply add it by searching for the keyword sqlite: the name of the extension is SQLite for Windows Runtime. Once you’ve installed it and restarted Visual Studio, you can now simply add SQLite to your application by adding a reference to two of the available libraries in the Extensions panel: Microsoft Visual C++ Runtime Package and SQLite for Windows Runtime. You can access to the panel by right clicking on the project, choosing Add reference and selecting Extensions from the Windows menu.

  

  

  Be aware that, since the library uses C++ extensions, you can’t compile the application using as a platform the Any CPU option, but you should target a specific platform. To do that, open the Configuration manager from the Build menu and set the platform to one of the available options (x86, x64 or ARM).

  

  If you don’t do this, you’ll see a warning sign on the two references Microsoft Visual C++ Runtime Package and SQLite for Windows Runtime and the project won’t compile.

  

  And… you’re done! No more manually downloading the dll library and copying it to the Visual Studio project: you can simply go on, install sqlite-net and use the same code you’ve learned to use in my first post.

  Thanks to Tim Heuer for the tip and… happy coding!

subscribe via RSS