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

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:

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.

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.

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.

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.

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.

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

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.

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)

Minor changes were made to the WMAppManifest.xml file

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. .

In the App element, the Genre attribute changed from NormalApp to Apps.Normal

In the App element, the RuntimeType attribute changed from SilverLight to Silverlight. {notice the case difference on the L}

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.

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

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.

Other miscellaneous changes you might run into:

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.

OnOrientationChanging virtual method on PhoneApplicationPage has been removed; now you just get OnOrientationChanged To fix: remove references to Deprecated event

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.

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.

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

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.

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.

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.

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 )

Microsoft.Phone.Notification went away, reference Microsoft.Phone

Channel.ExceptionOccurred event is now Channel.ErrorOccurred

HttpNotificationChannel.BindToShellNotification is now HttpNotificationChannel.BindToShellTile ()

NotificationChannelExistsException has been removed. You can now check if HttpNotificationChannel.IsShellTileBound before you bind to Shell

ShellEntryPoint class is gone. We not use standard Uris

HttpNotificationChannel.ShellNotificationReceived is now HttpNoficationChannel.ShellToastNotificationReceived

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.

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

open App.xaml and remove all the Application.Resources

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:

Search for

Replace with:

PhoneTextPageTitle1Style

PhoneTextNormalStyle

PhoneTextPageTitle2Style

PhoneTextTitle1Style

PhoneTextApplicationNameStyle

PhoneTextNormalStyle

PhoneTextTitleNameStyle

PhoneTextTitle1Style

Fixing your WMAppManifest.xml file

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:

XNA projects used to have an PlaceHolderString=”Default task” on the WMAppManifiest.xml this XML attribute is not longer valid, please remove it.

In the App element, the Genre attribute changed from NormalApp to Apps.Normal

In the App element, the RuntimeType attribute changed from SilverLight to Silverlight. {notice the case difference on the L}

Do clean-up or update the auto-generated metadata on your WMAppManifest, including App.Author, App.Description and App.Publisher

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

<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)

Remove old workarounds:

Remove checking for 0 == ManipulationDeltaEventArgs.*.Scale.

TransformToVisual and FindElementsInHostCoordinates. Orientation has been fixed and now we rotate the application frame, so these workarounds are no longer needed.

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.