WP to W8: API Mapping

This article is part of a series about my experience porting apps from Windows Phone to Windows 8. Official porting guidance can be found here and don’t forget to follow the Building Windows 8 blog and the Windows 8 App Developer blog for the latest information.

 

This article will be what my co-worker and friend Ryan Lowdermilk likes to refer to as a “SEO piece”. What Ryan means is while it may not make for easy chair reading, it will still meet a need for those searching for a particular piece of information. The information in this article is how commonly used Windows Phone APIs and XAML features map (or do not map) to their Windows 8 counterparts.

There won’t be a lot of dialog in this article. I’ll mention what the API is used for, show the Windows Phone version and show the Windows 8 version. If there are any important tricks to note, I’ll list those too.

XAML Namespaces

As mentioned in the first post, namespaces are declared differently

WP – xmlns:imgsch="clr-namespace:ImageSearch;assembly=…"

W8 – xmlns:imgsch="using:ImageSearch"

 

We change clr-namespace: for using: and we no longer have to specify the assembly name. This is nice because the namespace is resolved across assemblies, so we don’t have to have multiple namespace declaration if the same namespace is used in multiple dlls.

 

XAML Constants

Native Types (string, int) are in a different namespace:

WP – <sys:String x:Key="AppName">Foo</sys:String>

W8 – <x:String x:Key="AppName">Foo</x:String>

 

These kinds of constants are rarely used in Xaml, but they do come in handy for reusable strings like the application name. Just be aware that in Windows 8 you use the x: prefix for these types.

 

Touch Input

Windows 8 has a unified input system and no longer supports mouse-specific events:

WP – MouseLeftButtonUp="eventhandler"

W8 – PointerReleased="eventhandler"

 

The eventhandler above would get called whenever the user releases the right mouse button, raises their finger off the display or removes the pen from the surface. All three input devices are considered “pointers” and each “pointer” can be tracked individually if desired.

Even better, consider using the new gesture and Item events:

W8 – Tapped="eventhandler"

W8 – ItemClick="eventhandler"

Note: Don’t forget IsItemClickEnabled="True"

 

The Item events like ItemClick are especially valuable because you know that a) an item was actually tapped and b) which item it was. This is so much better than trying to use the SelectionChanged event or LeftMouseButtonUp and checking the SelectedItem property.

 

Event Handler Changes

RoutedEventArgs is still used for most control events like button click. However, RoutedEventArgs is now in a different namespace (and you’ll have to change it in your code behind):

WP – System.Windows.RoutedEventArgs

W8 – Windows.UI.Xaml.RoutedEventArgs

 

Since mouse events are gone,MouseButtonEventArgs is too. Mouse events are traded for gesture or pointer events:

WP – System.Windows.Input.MouseButtonEventArgs

W8 – Windows.UI.Xaml.Input.TappedRoutedEventArgs

W8 – Windows.UI.Xaml.Input.PointerRoutedEventArgs

 

 

Navigation

On Windows Phone we navigate to a Uri and we pass any parameters as part of the query string. On Windows 8 we navigate to the Type of the page and parameters can be passed as whole objects.

Windows Phone 7

NavigationService.Navigate(new Uri("/DetailsPage.xaml?Id=5", UriKind.Relative));

 

Windows 8

Frame.Navigate(typeof(DetailsPage), e.ClickedItem);

 

 

Storing Settings – Local

Both Windows Phone and Windows 8 provide a way to store application settings between runs on the same device.

Windows Phone 7

settings = IsolatedStorageSettings.ApplicationSettings; settings["exampleSetting"] = "Hello Phone";

 

Windows 8

settings = ApplicationData.Current.LocalSettings;   container = settings.CreateContainer(“main", ApplicationDataCreateDisposition.Always); settings.Containers["main"].Values["exampleSetting"] = "Hello Windows";

 

 

Storing Settings – Roaming

Windows 8 provide a way to store application settings that will get synchronized across the users devices. For more information see Guidelines for roaming application data.

Windows Phone 7

Not an option

 

Windows 8

settings = ApplicationData.Current.RoamingSettings;   // The rest is the same as local settings

 

 

Storing Files – Local

Both Windows Phone and Windows 8 provide a way to store files that belong to the application.

Windows Phone 7

using (var store = IsolatedStorageFile.GetUserStoreForApplication()) { store.CreateDirectory("SampleDirectory"); rootFile = store.CreateFile("SampleFile.txt"); // Open stream rootFile.Close();                      // Stream must be closed }

 

Windows 8

folder = ApplicationData.Current.LocalFolder;   // This is a StorageFile. It is not open. file = await folder.CreateFileAsync("SampleFile.txt", CreateCollisionOption.ReplaceExisting); // Writes text and closes file in one line await FileIO.WriteTextAsync(file, "Hello World");

 

 

Storing Files – Roaming

Windows 8 provide a folder for files that will automatically get synchronized across the users devices. For more information see Guidelines for roaming application data.

Windows Phone 7

Not an option

 

Windows 8

folder = ApplicationData.Current.RoamingFolder; // The rest is the same as a local file

 

 

Storing Files – Temporary

Windows 8 provide a folder for files that will automatically get deleted by the system maintenance task.

Windows Phone 7

Not an option

 

Windows 8

folder = ApplicationData.Current.TemporaryFolder;   // The rest is the same as a local file

 

 

Creating a Secondary Tile

Both Windows Phone and Windows 8 offer secondary tiles, but they are created and updated in different ways.

Windows Phone 7

tileData = new StandardTileData { // Set tile data } ShellTile.Create(new Uri("/ItemDetail.xaml?Id=123", UriKind.Relative), tileData);

 

Windows 8

tile = new SecondaryTile(         tileId,                          // Tile ID         shortTitle,                      // Tile short name         title,                           // Tile display name         "Id=123",                        // Activation argument         TileOptions.ShowNameOnLogo,     // Tile options             "ms-appx:///images/someImage.png"     // Tile logo     ); tile.RequestCreateAsync();

 

 

Updating the Primary Tile

Important: On Windows 8, tiles are created using XML instead of classes. Microsoft has created helper classes to work with tiles as objects instead of XML. These helper classes are included in the App tiles and badges sample. The Windows 8 code below leverages these helper classes.

Windows Phone 7

tile = ShellTile.ActiveTiles.First(); if (tile != null) { tileData = new StandardTileData { // Set tile data } tile.Update(tileData); }

 

Windows 8

wide = TileContentFactory.CreateTileWideImageAndText01(); square = TileContentFactory.CreateTileSquareImage(); wide.SquareContent = squareContent;   // Set wide and square tile data wide.TextCaptionWrap.Text = "This tile uses images"; wide.Image.Src = "ms-appx:///images/redWide.png"; square.Image.Src = "ms-appx:///images/graySquare.png";   // Update TileUpdateManager.CreateTileUpdaterForApplication().Update(wide.CreateNotification());

 

 

Updating the Secondary Tile

Important: On Windows 8, tiles are created using XML instead of classes. Microsoft has created helper classes to work with tiles as objects instead of XML. These helper classes are included in the App tiles and badges sample. The Windows 8 code below leverages these helper classes.

Windows Phone 7

tile = ShellTile.ActiveTiles.FirstOrDefault(<LINQ Query>); if (tile != null) { tileData = new StandardTileData { // Set tile data } tile.Update(tileData); }

 

Windows 8

wide = TileContentFactory.CreateTileWideImageAndText01(); square = TileContentFactory.CreateTileSquareImage(); wide.SquareContent = squareContent;   // Set wide and square tile data wide.TextCaptionWrap.Text = "This tile uses images"; wide.Image.Src = "ms-appx:///images/redWide.png"; square.Image.Src = "ms-appx:///images/graySquare.png";   // Update TileUpdateManager.CreateTileUpdaterForSecondaryTile(tileId).Update(wide.CreateNotification());

 

 

Toasts

Important: On Windows 8, toasts are created using XML instead of classes. Microsoft has created helper classes to work with toasts as objects instead of XML. These helper classes are included in the Toast notifications sample. The Windows 8 code below leverages these helper classes.

Windows Phone 7

var toast = new ShellToast {     Title = "Title",     Content = "Toast content",     NavigationUri = new Uri("ItemDetail.xaml?Id=123", UriKind.Relative) }; toast.Show();

 

Windows 8

toast = ToastContentFactory.CreateToastImageAndText02(); toast.TextHeading.Text = "Heading text"; toast.TextBodyWrap.Text = "Body text that wraps."; toast.Launch = “Id=123"; toast.Image.Src = "ms-appx:///images/graySquare.png";   ToastNotificationManager.CreateToastNotifier().Show(toast.CreateNotification());

 

 

Location

Windows Phone 7

watcher = new GeoCoordinateWatcher(); watcher.PositionChanged += watcher_PositionChanged; watcher.TryStart(false, TimeSpan.FromMilliseconds(2000));   // Handler private void watcher_PositionChanged(object sender, GeoPositionChangedEventArgs<GeoCoordinate> e) { … }

 

Windows 8

locator = new Geolocator(); locator.PositionChanged += locator_PositionChanged;   // Handler private void locator_PositionChanged(Geolocator sender, PositionChangedEventArgs e) { … }

 

 

Accelerometer

Windows Phone 7

accelerometer = new Accelerometer(); accelerometer.ReadingChanged += ReadingChanged;   // Handler private void ReadingChanged(object sender, AccelerometerReadingEventArgs e) { … }

 

Windows 8

accelerometer = Accelerometer.GetDefault(); if (accelerometer != null) {     accelerometer.ReadingChanged += ReadingChanged; }   // Handler private void ReadingChanged(object sender, AccelerometerReadingChangedEventArgs e) { … }

 

 

Open Photo

Windows Phone 7

chooser = new PhotoChooserTask(); chooser.Completed += chooser_Completed; void chooser_Completed(object sender, PhotoResult e) { if (e.TaskResult == TaskResult.OK) { BitmapImage bmp = new BitmapImage(); bmp.SetSource(e.ChosenPhoto); } }

 

Windows 8

var picker = new FileOpenPicker(); picker.ViewMode = PickerViewMode.Thumbnail; picker.SuggestedStartLocation = PickerLocationId.PicturesLibrary; picker.FileTypeFilter.Add(".jpg"); var file = await picker.PickSingleFileAsync();   if (file != null) { … }

 

 

Capture Photo

Windows Phone 7

chooser = new CameraCaptureTask (); chooser.Completed += chooser_Completed; void chooser_Completed(object sender, PhotoResult e) { if (e.TaskResult == TaskResult.OK) { BitmapImage bmp = new BitmapImage(); bmp.SetSource(e.ChosenPhoto); } }

 

Windows 8

var camera = new CameraCaptureUI(); var file = await camera.CaptureFileAsync(CameraCaptureUIMode.Photo);   if (file != null) { … }

 

 

Capture Video – System UI

On Windows Phone 7 there is no system-provided UI for capturing video (though a custom UI can be created). On Windows 8, the system UI can be used to capture MP4 and WMV files.

Windows Phone 7

Not an option

 

Windows 8

CameraCaptureUI camera = new CameraCaptureUI(); camera.VideoSettings.Format = CameraCaptureUIVideoFormat.Mp4;   StorageFile file = await camera.CaptureFileAsync(CameraCaptureUIMode.Video);   if (file != null) { … }

 

 

Capture Video – Custom UI

Custom video capture on both platforms involves placing an element on the screen that will display the video preview, creating a capture device, connecting the visual element with the capture device, and capturing the video to a target file.

Windows Phone 7

videoCaptureDevice = CaptureDeviceConfiguration.GetDefaultVideoCaptureDevice();   captureSource = new CaptureSource(); fileSink = new FileSink();   fileSink.IsolatedStorageFileName = "CameraMovie.mp4"; fileSink.CaptureSource = captureSource;   videoBrush.SetSource(captureSource); viewfinderRectangle.Fill = videoBrush;   captureSource.Start();

 

Windows 8

mediaCapture = new MediaCapture(); await mediaCapture.InitializeAsync();   previewElement.Source = mediaCapture;   storageFile = await KnownFolders.VideosLibrary.CreateFileAsync("CameraMovie.mp4");   profile = MediaEncodingProfile.CreateMp4(VideoEncodingQuality.Auto);   await mediaCapture.StartRecordToStorageFileAsync(profile, storageFile);

About these ads