Windows Phone updates for Windows Runtime via C#

  • Article

9780735679276fIn November 2013, Microsoft Press published Windows Runtime via C# (320 pages; ISBN: 9780735679276), by Jeffrey Richter and Maarten Van De Bospoort. The book offers expert guidance on leveraging the Windows Runtime (WinRT) API to produce Windows Store apps. Since then, Microsoft introduced Windows Phone 8.1, allowing developers to write Windows Phone apps by using WinRT. Because of this, all the content in Windows Runtime via C# is now also applicable to Windows Phone app developers. This blog post was written by Jeffrey and Maarten. It goes through every chapter of the book and points out the few differences where the contents of the book are different for Windows Phone apps.

If you are building Windows Phone apps, use this blog post along with the book, and you’ll be prepared. Of course, there are obviously some things you can’t easily do on a phone. You don’t have access to system tools like RegEdit or Process Explorer, and you can’t easily look into event logs or scheduled tasks. This also means that the Wintellect Package Explorer (described in the book) doesn’t work on the phone, because it is a Windows desktop app. By the way, all of the code accompanying the book has been updated to support Windows Store and Phone apps. The latest version of the code is downloadable from Wintellect’s website: Go to https://www.wintellect.com/Resources, find the entry for Windows Runtime via C# , and click on the blue “Source Code” button.

The differences between Windows Phone apps and Windows Store apps manifest themselves in different ways. Many of the differences have to do with the timing of releases. For example, the Windows.winmd file for Windows Phone defines a ValueSet class. This class will come to the Windows desktop in the future, but it is not there now. So, for a Windows Store app, you will not be able to use this class today. Some APIs (e.g., PickSingleFolderAsync) do exist in the winmd files for both Windows Store and Windows Phone apps, but you’ll get compiler warnings and calling them at run time has no effect. Then there are instances where some APIs (e.g., QueryOptions) exist, but calling them at run time throws a NotImplementedException. Finally, some APIs (e.g., CreateStreamedFileAsync) just don’t do anything.

Chapter 1: Windows Runtime primer

Windows Store and Windows Phone apps use slightly different Windows.winmd files. By default you’ll find the Windows Store version here:

C:\Program Files (x86)\Windows Kits\8.1\References\CommonConfiguration\Neutral\Windows.winmd

And you’ll find the Windows Phone flavor here:

C:\Program Files (x86)\Windows Phone Kits\8.1\References\CommonConfiguration\Neutral\Windows.winmd

Chapter 2: App packaging and deployment

The mechanism for app packaging and the manifest files are largely the same. There are some minor differences in the manifest files:

  • Packaging For Windows Phone, there is no Publisher field allowing you to choose a certificate. As a result, you’ll find that the AppxMetadata Folder mentioned in Table 2.5, is missing from the AppX package as well as the AppxSignature.p7x. Because there is no certificate, the Publisher name field is set to the name of the logged-in user.
  • Capabilities Windows Phone has two additional capabilities: appointments and contacts. These capabilities give the app access to the user’s appointments and contacts stores, respectively. According to the documentation, this is supported for both Windows Store apps and Windows Phone apps, but neither the manifest editor nor the AppX manifest XSD support it. On the other hand, Windows Phone handles network capabilities different from Windows Store apps. The Windows Phone manifest design shows only Internet (Client & Server). However, you can specify Internet (Client) and Private Networks (Client & Server) in the manifest’s XML directly. However, there is no need to because having any network capability grants full access to network on Windows Phone. Additionally, even if you specify no network capabilities at all, networking is always enabled when debugging your app with Visual Studio. Finally, the book mentions that the user will see an additional message dialog when your app uses some devices that are deemed highly intrusive, such as Location, Microphone, or webcam. On Windows Phone, no such dialog is shown to the user; the app can simply use the device.
  • Declarations The Windows Phone manifest editor shows a subset of the Declarations that you’ll see for a Windows Store app: Background Tasks, Cached File Updater, File Open and Save Picker, File Type Associations, Protocol, and Share Target. You’ll find the other declarations when you edit the manifest file manually. According to the documentation, however, these declarations are not supported on Windows Phone. Windows Phone has one declaration that Windows Store apps do not have: UpdateTask. It works just like a Background Task with a ServicingComplete trigger. I’ll discuss it below in the section on Chapter 9, “Background tasks.”

There are also some differences between the Windows Store app and Windows Phone app version of the WinRT Package class. For example, DisplayName and Description are not available for Windows Phone, while GetThumbnailToken, InstallDate, and Launch are available only for Windows Phone.

The book mentions three mechanisms for deploying a Windows Store package:

  1. The mechanism of restricted deployment with PowerShell is not available for Windows Phone. Hence there is no need for the PowerShell script and other files mentioned in Table 2-4 (files with extensions .cer, .ps1, and .resources). You can remotely deploy from the debugger to an unlocked Windows Phone and the app will remain there after debugging.
  2. Enterprise deployment is available for Windows Phone, but it works slightly differently. See https://msdn.microsoft.com/en-us/library/windowsphone/develop/jj206943(v=vs.105).aspx for more information.
  3. Deploying to the Windows Store also works slightly differently between Windows Store and Windows Phone apps. You can publish your Windows Phone app to the Public Store but hide the app from users who are browsing the store. Users can find the app only with an app link. There is also an option for Beta where you can distribute your app to a max of 10,000 users. You have to predefine these beta users by using their Microsoft account email.

Similar to the simulator for Windows Store apps, Visual Studio offers an emulator for debugging Windows Phone apps. The simulator is implemented as a Terminal Services session, but the emulator is an actual Hyper-V virtual machine. Its UI offers similar buttons for rotation and touch simulation, and it allows you to take screenshots you can upload to the store. In addition, the emulator has some buttons you can use to emulate sensors and devices such as accelerometer, GPS, ALS, gyroscope, magnetometer, NFC, and cameras. You can also emulate different quality of mobile broadband network settings to test how your app functions with limited bandwidth. Finally, you can use the emulator to add an SD card and simulate WNS notifications. See https://msdn.microsoft.com/en-us/library/windowsphone/develop/dn629629.aspx for more information.

In most situations, you’ll build your app using a platform target of Any CPU (which is the default). However, just as with Windows Store apps, you must switch to a specific CPU architecture if your app depends on a native DLL. In this case, you’ll have to switch between ARM if you’re debugging on an attached phone device and x86 if you’re debugging in the emulator.

Chapter 3: Process model

Windows Phone does not support some of the ActivationKind enum values, such as RestrictedLaunch, Contact, and LockScreenCall. But Windows Phone adds some new ActivationKind values, including VoiceCommand, WalletAction, and four continuation activations (PickFileContinuation, PickSaveFileContinuation, PickFolderContinuation, and WebAuthenticationBrokerContinuation). [Editor’s note: Jeffrey Richter is planning a future blog post where he will discuss the four continuation activations in more detail and how to write a single block of code that works for both Windows Store and Windows Phone apps.]

Then there are some differences that have to do with the fact that Windows Phone hardware is just different than PC hardware. For example, on Windows Phone you have one small screen, so showing windows side-by-side or on a different monitor doesn’t make sense. Thus, the ApplicationViewSwitcher class that allows you to have multiple windows for your app does not exist on Windows Phone. Another example is that PC hardware does not have a hardware back button like Windows Phone. This means you’ll have to write code to explicitly handle the Windows Phone back button so that it behaves correctly for your app.

Finally, because a Windows Phone device typically has less RAM than a PC, memory management becomes more important. You’ll see Windows Phone apps being terminated more frequently than on a PC. Efficiently managing memory and aggressively releasing resources become more important. Fortunately, the emulator can emulate a phone having just 512MB of RAM, thereby allowing you to test your app on a memory-constrained system.

Chapter 4: Package data and roaming

Microsoft allows users to recover the state of their phone if their phone is lost or destroyed and the user acquires a new phone. To accomplish this, the contents of LocalSettings and LocalFolder is periodically backed up to the user’s OneDrive account so that it can be downloaded on to a new phone in the future. On Windows Phone, the ApplicationData class has a new folder: LocalCacheFolder. Your app can put data in this folder if it truly does not want data sync’d to OneDrive and another phone.

If your Windows Store app and your Windows Phone app share the same package identity (package family name), the contents of the RoamingFolder and RoamingSettings will sync across the PC and the phone. See the bottom of https://msdn.microsoft.com/en-us/library/windows/apps/hh465094.aspx. Also, note that the Roaming Monitor tool mentioned in the book does not seem to be maintained and is available only for Visual Studio 2012.

The Wintellect Package explorer doesn’t work on Windows Phone because it is a desktop app. The same holds for the ApplicationDataManager.CreateForPackageFamily API that a desktop app can use to preconfigure settings or data in a package’s ApplicationData. You can use the Isolated Storage Explorer to look at your app’s data files on the emulator or Windows Phone; see https://msdn.microsoft.com/en-us/library/windowsphone/develop/dn629254.aspx.

Chapter 5: Storage files and folders

Windows Phone does not implement the Windows.Storage.Search.QueryOptions class although it is in the Windows.winmd file (and documented as supported). This means that code using this API will compile without warnings or errors, but when your app calls the QueryOptions constructor, NotImplementedException is thrown. The same thing happens with the KnownFolders Homegroup and MediaServerDevices. However, the Windows.Storage.DownloadsFolder class is not available for Windows Phone, preventing you from compiling code that attempts to use it.

Interestingly enough, the folder and file pickers (e.g., PickSingleFolderAsync) have a Deprecated attribute for Windows Phone, so at least you get a compile warning that indicates you need to use PickFolderAndContinue. The file and folder picker mechanisms work substantially differently on Windows Phone due to memory limitations. Jeffrey will discuss these more in a future blog post. By the way, on Windows Phone, a file obtained via the file open picker is read-only while files obtained via the file save picker are readable and writable. File and protocol associations work identically between Windows Store and Windows Phone apps. However, the Edit flags (indicating whether the file is safe for opening, etc.) are not there in manifest editor on Windows Phone.

Windows Phone does not support accessing files via UNC paths. The code below (which works in a Windows Store app having a .txt file type association and Private Networks and Enterprise Authentication capabilities), throws an ArgumentException on Windows Phone:

var file = await StorageFile.GetFileFromPathAsync(@"\\remotePC\public\data.txt");

Chapter 6: Stream input and output

The CreateStreamedFileAsync method is not implemented on Windows Phone. It does compile without warnings, and you can run it without encountering any exceptions. It simply fails to do what you expect it to do. On the other hand, the ContentIndexer class is not in the Windows Phone’s Windows.winmd file, preventing your code from compiling if you attempt to use it.

Chapter 7: Networking

As mentioned in the Chapter 3 section, Windows Phone handles network capabilities differently. There are some other minor differences related to networking:

  • The ContentPrefetcher class is not available in the Windows Phone’s Windows.winmd file.
  • The Windows Phone manifest designer does not show the Shared User Certificates declaration, but you can add it manually to the manifest’s XML file.

Chapter 8: Tile and toast notifications

The table below shows all the various logos supported by Windows Store and Windows Phone apps and their pixel widths and heights (square logos show one number representing the logo’s width and height). Boxes having a green background represent logos that you must provide in your package.

 image

On Windows Phone, the SecondaryTile functions RequestCreateAsync and RequestDeleteAsync don’t show a confirmation dialog; they just work.

Windows Phone supports only two badge glyphs: alert and attention. If you try to show any of the other glyphs, it will clear the badge from the tile. Number badges are supported the same way.

On Windows Phone, toast notifications appear at the top of the screen and there are some limitations:

  • Changing the sound scheme does not make a difference. The user sets the sound for notifications in phone settings.
  • There is no difference between long and short duration toasts.
  • The image is ignored and the square 150x150 logo.png is used.
  • Looping is ignored.

The user can find the toast history in the Windows Phone action center. Windows Phone offers a History property on the ToastNotificationManager class; this property returns a ToastNotificationHistory object. With this object, you can remove toast notifications from the action center.

Chapter 9: Background tasks

Background tasks are probably the area with the most differences. Conceptually, it all works the same. However, with Windows Phone, your app must call BackgroundExecutionManager.RequestAccessAsync or its background tasks will simply never run.

Windows Phone also has a new package declaration: Update Task. Windows runs this task when the package in installed on the user’s phone; this allows the package to update the schema of package data or perform some other maintenance task (like get a new WNS channel URI). This is a nice improvement over how the ServiceComplete trigger works with Windows Store apps. For the ServicingComplete trigger to work, the first version of a package must register a background task, which will then run when the second version of the package is installed. The Windows Phone Update Task doesn’t require that the developer had the forethought to have registered this task in the first version.

Windows Phone also has a DeviceUseTrigger, allowing a background task to access sensors. See https://msdn.microsoft.com/en-us/library/windows/apps/xaml/dn630194.aspx for more information.

Below is a short list of the most important differences related to Windows Phone background tasks. For more information, see https://msdn.microsoft.com/en-us/library/windows/apps/xaml/Hh977056(v=win.10).aspx.

  • Timer trigger has a minimum of 30 minutes on Windows Phone versus 15 minutes for Windows Store apps.
  • Windows Phone makes no distinction between lock screen and non–lock screen apps, but all apps need to call BackgroundExecutionManager.RequestAccessAsync.
  • Windows Phone has a more restricted memory quota for background tasks.
  • No background tasks run if the device is in battery saver mode (except for PushNotificationTrigger).
  • Windows Phone does not support the ControlChannelTrigger.

Finally, Windows Phone introduces some new triggers:

  • CachedFileUpdaterTrigger. Interesting since there is a CachedFileUpdater contract for both Windows Phone and PC. The documentation mentions that Windows Phone can’t launch an app without UI (which the CachedFileUpdater can do).
  • ChatMessageNotificationTrigger
  • DeviceManufacturerNotificationTrigger
  • SmartcardTrigger
  • DeviceConnectionChangeTrigger (used to monitor connections to devices, such as BTLE or GATT)
  • RfcommConnectionTrigger (fires when an RFComm device is near)
  • GattCharacteristicNotificationTrigger (indicates a change in Gatt connection)

Chapter 10: Sharing data between apps

Sharing data is almost identical between Windows Store and Windows Phone apps. The HUGE difference is that Windows Phone does not support the Clipboard class, so Windows Phone apps cannot manipulate the Clipboard at all.

As for the Share contract, a Windows Phone app can use the QuickLinks class, but Windows Phone ignores QuickLinks.

Windows Phone does not have a concept of charms or multiple apps sharing the screen, so the share contract experience works differently on the phone. Because Windows Phone has no charms bar, your app must provide a button or other UI affordance to initiate a share operation by calling DataTransferManager.ShowShareUI. After this the UI experience and code is identical to that of Windows Store apps except that the phone does not allow the user to transition away from the sharing user interface while the share operation is underway. For this reason, Windows Phone’s ShareOperation class does not offer the DismissUI method. Sharing notifications (such as failed) show up in Window Phone’s action center.

Chapter 11: Windows Store

The Windows App Certification Kit (WACK) tool now supports Windows Phone apps. The tests for Windows Phone are a subset of the tests for Windows Store apps. Specifically, Windows Phone does not support the App Manifest Compliance, Performance, and Crashes and Hangs tests.

Since you don’t have easy access to the file system on Windows Phone, the WindowsStoreProxy.xml file used by the CurrentAppSimulator is harder to get to and edit. Fortunately, you can still add this file to your package and load it with CurrentAppSimulator.ReloadSimulatorAsync. The sample code accompanying Windows Runtime via C# demonstrates how to create and modify XML proxy files at run time so that you don’t need to manually create the file and install it on the phone.

In-app purchases made by a Windows Phone app are shared with Windows Store apps if both have same the same package identify (package family name).