Migrating apps from Windows Phone April CTP Refresh to the beta build

  • Article

There were a good number of breaking changes and new features introduced in the “beta” release of the Windows Phone Developer Tools.
Going forward from beta to RTM; the number of breaking changes will be minimal, so let’s just “buckle up” and migrate our code this once.
The migration is a lot easier than it sounds. I will first walk through the obvious breaking changes that the compiler will catch, and then share tips and workarounds in some of that ‘missing’ stuff that the compiler will miss. 
Once you have gotten through this, don’t forget to read my post on the new features in the beta release so you can start taking advantage of these.

Breaking changes:

  1. Namespaces and assembly changes:
    The following assemblies were removed, and merged into a single “Microsoft.Phone” assembly:
    Microsoft.Phone.Controls
    Microsoft.Phone.Controls.Navigation
    Microsoft.Phone.Controls.WebBrowser
    Microsoft.Phone.Controls.WebBrowserInterop
    Microsoft.Phone.Shell
    Microsoft.Phone.Notification
    Microsoft.Phone.Execution
    Microsoft.Phone.Info
    Microsoft.Phone.Tasks
    Microsoft.Devices
    To fix: change all your project references and all your namespaces declarations (xmlns) in XAML. See MigrationTips.1 below for details on namespaces.

  2. System.Device.Location assembly was merged into System.Device assembly
    To fix: change assembly references that were pointing to System.Device.Location and point them to System.Device assembly.

  3. Microsoft.Devices assembly was removed; the classes in this assembly were moved to Microsoft.Phone assembly. Some of the classes changed namespaces, but not all.
    To fix: change assembly references and reference Microsoft.Phone assembly.

  4. Application.Resources have been removed from App.xaml and templates have been changed
    To fix: you will need to remove these from your own App.xaml. Can’t leave them in because it would break theming; also, there are breaking changes (controls removed) that would prevent your app from running if you do not get rid of the resources. See below on MigrationTips.2 for details on what to remove and how.

  5. ToggleControlSwitch and ToggleControlButton have been removed.
    To fix: You should use ToggleButton and copy the template from RC version of ToggleControlSwitch. You will then need to add the touch gesture. Wait for a sample for this. I will post one soon.

  6. ListView and ListView Item were removed
    To fix: Use ListBox and a Template that matches the old ListViewItem template.

  7. Effects have been removed from the platform, this will be plan of record for v1 (the feature might come back later).
    In earlier builds, we had DropShadow, and Blur bitmap effects.  Unfortunately, these have been removed.
    Right now, your XAML is not breaking, but the usage of the effects is turning into a no-op.

    To fix: You should just remove the references to effects from XAML and code. You can use graphics (e.g. gradients for dropshadows) to try to get similar look & feel. Not exactly the same, but best workaround I can think of until Microsoft brings these back in a future version of the platform.

  8. A few classes were renamed or moved namespaces:  

    Type Old New New assembly (if changed)
    namespace Microsoft.Devices.NetworkInformation Microsoft.Phone.Net.NetworkInformation Microsoft.Phone.dll
    namespace Microsoft.Phone.License Microsoft.Phone.Marketplace Microsoft.Phone.dll
    class Microsoft.Phone.Controls.NavigatedEventArgs System.Windows.Navigation.NavigationEventArgs System.Windows.dll
    class Microsoft.Phone.Navigation.PhoneNavigationEventArgs System.Windows.Navigation.NavigationEventArgs System.Windows.dll
    class AccelerometerSensor Accelerometer  
    class AccelerometerReadingAsyncEventArgs AccelerometerReadingEventArgs  
    class AccelerometerStartFailedException AccelerometerFailedException  
    class WindowsPhoneEvents Microsoft.Phone.Shell.PhoneApplicationService Microsoft.Phone.dll
    class Microsoft.Phone.License.LicenseInfo Microsoft.Phone.Marketplace.LicenseInformation Microsoft.Phone.dll
    enum Microsoft.Phone.Shell.DownloadInterval Microsoft.Phone.Shell.UpdateInterval Microsoft.Phone.dll
    enum Microsoft.Phone.Shell.DownloadRecurrence Microsoft.Phone.Shell.UpdateRecurrence Microsoft.Phone.dll
    class NotificationChannelExceptionEventArgs NotificationChannelErrorEventArgs Microsoft.Phone.dll

    To fix: simply replace the namespace and/or class name and reference the new assembly (if applicable)

  9. Minor changes were made to the WMAppManifest.xml file

    1. XNA projects used to have an PlaceHolderString="Default task" on the WMAppManifiest.xml  this XML attribute is not longer valid.
       Fix: remove the attribute from manifest. .
    2. In the App element, the Genre attribute changed from NormalApp to Apps.Normal
    3. In the App element, the RuntimeType attribute changed from SilverLight to Silverlight.   {notice the case difference on the L}

  10. System.Reactive namespace was moved to Microsoft.Phone.Reactive and there is a new assembly called Microsoft.Phone.Reactive.dll
    The System.Concurrency and System.Disposable namespaces are now on this assembly.

  11. Removed ManipulationCompletedEventArgs.IsTapEvent property
    To fix: remove references to the property. You can use OnClick handlers.

  12. Choosers API are no longer returning on OnChooserReturn; they now have instance based events.
    The PhoneNumberChooserTask and PhotoChooserTask used to always return on an override on the Page hosting. They now have events that the task exposes and you can add the handler and listen to the return from any class you like.  The tasks have a Completed event you can listen to.

  13. Other miscellaneous changes you might run into:

    1. The ApplicationBarIconButton has a new Text property and it can't be empty.. whitespace does not work either.
      You must enter something; old projects will get an InvalidOperationException with message of “Text cannot be empty” if you try to use the buttons with no text.  
      To fix: enter some text for your button.
    2. OnOrientationChanging virtual method on PhoneApplicationPage has been removed; now you just get OnOrientationChanged
      To fix: remove references to Deprecated event
    3. Signature change on PhoneApplicationPage class
      override void OnNavigatedFrom(Microsoft.Phone.Navigation.PhoneNavigationEventArgs e)  becomes
      override void OnNavigatedFrom(System.Windows.Navigation.NavigationEventArgs e);
    4. AccelerometerReadingEventArgs was refactored and it no longer has a Value property wrapping the sensor data; you can now get to the X, Y, Z properties directly.
    5. I already mentioned that WindowsPhoneEvents class was replaced by  PhoneApplicationService class. 
      The events in these classes were also renamed from Paused to Deactivated and Resume to Activated.
    6. System.Windows.Browser.dll  has been finally removed. You should not have been using this assembly (since nothing worked, it was not supported).   The common reasons to look for this assembly included:
      HttpUtility class, which is in System.Windows.dll in the System.Net namespace.
      Interop between browser and Javascript.  If you are needing that, use the WebBrowser control and the ScriptNotify and
    7. Changed PhoneApplicationPage.ApplicationBar property from type ApplicationBar to IApplicationBar.
      Your old code should still work, but there might be a cast needed pending how you coded it.
    8. ManipulationDeltaEventArgs.CumulativeManipulation.Translation, ManipulationDeltaEventArgs.DeltaManipulation.Translation, and ManipulationDeltaEventArgs.TotalManipulation.Translation are now only populated when the user has moved certain number of pixels from original contact point.
    9. Scale property in ManipulationDeltaEventArgs.DeltaManipulation and ManipulationDeltaeventArgs.TotalManipulation has been changed to return 1 when there is no changes (instead of returning 0 in CTP Refresh); this mostly means you can go through your code, and remove the check you would have had to add before where you were detecting 0.0 and throwing it away.

  14. A few push notification changes (this list is best explained via sample, the new TrainingKit has a great hands-on lab that will walk you through these changes )

    1. Microsoft.Phone.Notification went away, reference Microsoft.Phone
    2. Channel.ExceptionOccurred event is now Channel.ErrorOccurred
    3. HttpNotificationChannel.BindToShellNotification is now HttpNotificationChannel.BindToShellTile ()
    4. NotificationChannelExistsException has been removed.  You can now check if HttpNotificationChannel.IsShellTileBound before you bind to Shell
    5. ShellEntryPoint class is gone. We not use standard Uris
    6. HttpNotificationChannel.ShellNotificationReceived is now HttpNoficationChannel.ShellToastNotificationReceived 

Steps for migrating your code (referenced above as MigrationTips.X ) :

  1. Fix all project references.  

    1. Remove references to Microsoft.Phone.Controls, Microsoft.Phone.Controls.Navigation, Microsoft.Phone.Controls.WebBrowser, Microsoft.Controls.WebBrowser.interop

    2. Add a reference to Microsoft.Phone assembly

    3. Do a global search and replace for the xmlns declarations. For example:

      Search for Replace with
      clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Navigation clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone
      clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.WebBrowser clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone
      clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone.Shell clr-namespace:Microsoft.Phone.Shell;assembly=Microsoft.Phone
      clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone
         

      The list above is not all inclusive, but it is the most common one and shows you the “pattern” to use: don’t replace the whole xmlns declaration, just replace the clr-namespace strings, and your code will be easier to migrate.  The search above can be applied to just XAML files, making it slightly quicker to replace all.

  2. Fixing themes and App.xaml resources issues:
    Assuming you had not added your own resources,

    1. open App.xaml and remove all the Application.Resources
    2. Do a global find/replace for following strings, these are resources that were in App.xaml but are not automatically inserted by the run-time. Most of these are used by the default Mainpage.xaml that every new project includes:
  3. Search for Replace with:
    PhoneTextPageTitle1Style  PhoneTextNormalStyle
    PhoneTextPageTitle2Style PhoneTextTitle1Style
    PhoneTextApplicationNameStyle PhoneTextNormalStyle
    PhoneTextTitleNameStyle PhoneTextTitle1Style

  4. Fixing your WMAppManifest.xml file

    1. The easiest way to fix your manifest is to create a new empty project with same name than your existing one, and copy the whole WMAppManifest to your project.  You can also copy a few of the attributes, elements. These are the commone ones to watch out for:
    2. XNA projects used to have an PlaceHolderString="Default task" on the WMAppManifiest.xml  this XML attribute is not longer valid, please remove it.
    3. In the App element, the Genre attribute changed from NormalApp to Apps.Normal
    4. In the App element, the RuntimeType attribute changed from SilverLight to Silverlight.   {notice the case difference on the L}
    5. Do clean-up or update the auto-generated metadata on your WMAppManifest, including App.Author, App.Description and App.Publisher
    6. If you do not have capabilities (maybe you were not using refresh but MIX build) copy the whole  <App><Capabilities> element from the empty project to yours
    7. <Tasks> collection has a <DefaultTask> element with a new NavigationPage attribute.  In previous builds this was set via code in App.xaml via the <Application.RootVisual> you can use either. They both work, just make sure you have one or the other approach (and not both)

  5. Remove old workarounds:

    1. Remove checking for 0 == ManipulationDeltaEventArgs.*.Scale.
    2. TransformToVisual and FindElementsInHostCoordinates. Orientation has been fixed and now we rotate the application frame, so these workarounds are no longer needed.
    3. You can now reference signed assemblies again, so if you had used the workaround to unsign them, you can remove it again.

Closing Advise/asks:
Please share back your experiences and tips!!     I know this document is not 100% comprehensive. If you run into one change that I missed or get stuck along the way, please email me directly [via email blog author on the sidebar column] so we can update and improve this document.

Don’t forget to read the release notes . This document overlaps with some of the content in the release notes, but I focused on migration, so there are other tips and known issues there that will be useful to you; please take a look at the release notes. 

Happy Windows Phone coding!