Hi, I’m John Sheehan, Partner Architect on the Windows Development team.

We really appreciate you building apps for the preview releases. Your feedback helps us make Windows 8 great. Of course, building on a preview means that you need to make updates to your apps for each preview release – that’s what this post is all about, migrating your projects from the Developer Preview to the Consumer Preview. I’m going to highlight some of the changes here, but for a detailed guide to the changes, you can download the white paper on migrating your apps from //Build to Windows 8 Consumer Preview from the Dev Center.

When you start thinking about migrating your apps to the Consumer Preview, I’m sure some of you are wondering why we chose to make some of these changes. I can personally assure you that we take every change seriously. Some improvements are made based on direct feedback we hear: a feature is confusing so we make it easier, or it lacks some capability you told us you need. Other times, after we complete a feature and start using it ourselves, we realize it just didn’t land where we wanted it to, so we take what we learned and make it better. There are many factors we consider. Rest assured, we carefully think through every decision, with the goal of creating a great platform for your Metro style apps.

I had to go through the migration process with the Connect 4 app I built on the Developer Preview.  I know it takes a bit of work to do the migration.  But if you follow the steps outlined in the post and document, you’ll be up and running pretty quickly.

So, let’s dive in!

Starting fresh

While it may be tempting to keep your existing project and try to migrate it to the Consumer Preview, enough has changed since the Developer Preview that it’s best to start with a new project. For example, in Visual Studio there were a number of changes in project definition files: the JavaScript project extension was renamed to .jsproj, and the the import statement changed in .csproj/.vbproj files. Your existing project won’t even open because of these changes. After you start a new project, you can move pieces of your old project into the new one.

These steps are a good guideline for migrating your code. You can also find these steps and many more migration details in //Build to Windows 8 Consumer Preview. (I’ll mention this several more times before you're done reading this post!)

  1. Create a new project in Visual Studio and pick the template that most closely resembles the UI of your existing app.
  2. If the new Item Templates support the contracts and features you need, like the File Picker contract or the Search contract, use them instead of trying to reuse your existing code.
  3. After you reconstruct the basic elements of your UI using the new templates, migrate your visual and audio assets from your old project into your new one. Limit the additional code you bring into the project to just be the custom business logic that was at the heart of your app.
  4. Finally, begin to stitch your new UI (structured with the new templates) to your visual and audio assets and to your back-end logic.

By following these steps, you’ll naturally incorporate many of the changes into your app’s code. Now let’s discuss some specific changes that can affect your code as you move it into the new templates.

General changes that affect all languages

First, I’d like to describe some changes to the basic programming model that affect developers in any programming language.

Manifest changes

The manifest is the DNA of your app. As we make changes in the platform, they often have an impact on the structure of the manifest. Given the number of changes in the manifest, it will likely be easiest to start with the new manifest that gets created when you create your new project and use the manifest editor to modify this new manifest, rather than trying to port your existing manifest.

Hot start async model

In the Developer Preview, all async methods were cold start. When you called an async method, you got back an async operation object. You registered for completion and progress callbacks (if applicable) on this operation object and then called IAsyncInfo.Start. The problem with this model was that the call to Start was redundant. As a developer you could reasonably expect that the async operation starts when you make the initial method call.

To make the async model more intuitive, we changed it to a hot start model. In the Consumer Preview, when you call an async method, you get back an async operation object but you don't need to call Start. Instead, the operation is implicitly started when the async method is called. Because we don’t need Start anymore, we removed it from IAsyncInfo.

If you have already been using .then() (JavaScript) or await (C#), this change doesn’t affect you.

Additionally, we added PPL tasks to make async programming easier in C++. I recommend that you take a look at the tutorial in //Build to Windows 8 Consumer Preview and migrate your async code to the PPL model.

Deterministic lifetime management of Windows Runtime objects (IClosable)

Windows Runtime APIs can give your app access to system resources, such as file handles and network sockets. These resources are limited and often the user or other apps can’t use them when your app is accessing them. Your app is responsible for freeing these resources after it’s done using them. However in the Developer Preview it was difficult to explicitly free these resources and so many apps held on to them longer than necessary.

In the Consumer Preview, Windows Runtime APIs that access these system resources can control their lifetimes. For example, in JavaScript these WinRT objects expose a close method and in C# they implement the IDisposable interface. With lifetime management exposed directly on these WinRT APIs, it is now much easier to free system resources when your app is done using them. Use these new lifetime management capabilities to reduce the resource consumption of your app and to make sure your customers always have access to their system resources, like files, when your app is not using them.

Simplified WinRT threading model

We received feedback from you that the COM threading model underlying WinRT was confusing, because it introduced considerations that don’t exist in other programming environments. Some of the issues were:

  • Object lifetime is tied to the apartment in which it was created.
  • Automatic marshaling behavior violates the principle of least surprise.
  • Event callbacks often run on an unexpected thread.
  • Delegates are inconsistent across C++ / C#.

To fix these issues, we changed the threading model for WinRT objects. At a high level, the changes are:

  • An object’s lifetime is now tied to open references. The object remains valid until the last reference goes away.
  • Most objects are agile. Calls to methods on these objects happen directly on the current thread.
  • The most common events are routed back to the thread where event was registered. There are still cases where event callbacks can occur on a worker thread. But, they are less common.
  • C++ delegates now default to being agile, just like C# delegates did in the Developer Preview. Delegates can still marshal back to the thread they were created on if you specify CallbackContext::Same when creating the delegate.

Windows.ApplicationModel (contracts) changes

We introduced many improvements to the contracts in the Consumer Preview. These improvements come in the form of changes to the APIs, functionality, manifest registrations, and UI. Contracts like Search, Share, Settings, the File Picker, etc. have all been improved in one way or another. For example we added a new File Picker contract, FileSavePickerActivatedEventArgs, that allows your app to act as a Save As target. This is an incredibly powerful feature – with it you can build a picker that lets users open and save files to your cloud as simply as if they were on the local disk. To accommodate this change, we renamed the File Picker contract in the Consumer Preview to FileOpenPickerActivatedEventArgs.

For contracts that are supported in Visual Studio the easiest way to incorporate these changes is to use the new item Template to create the contract from scratch. You can then add your existing code that supports the contract to the new template.

URI protocol schemes

A number of APIs relied on URI protocol schemes to access content in the app’s package or in the app’s ApplicationData state locations. These APIs include resource tags in Metro style apps written in HTML/CSS/JS, Live Tiles, the ResourceLoader APIs, the XAML WebView control, and the file Storage APIs.

We updated protocol names to make them consistent across all Metro style apps and Windows 8 integration points. We also renamed these protocol schemes:

Developer Preview scheme

Consumer Preview scheme

ms-wwa://

ms-appx://

ms-wwa-web://

ms-appx-web://

localfolder://

ms-appdata://

Additionally, XAML apps are now restricted to using supported protocol schemes, like ms-appx://, to access resources.

Important HTML/CSS/JS Metro style app changes

Several changes in the Consumer Preview are specific to Metro style apps written in HTML/CSS/JS. Here are some of the notable changes.

Control changes

The JavaScript and HTML controls available in the Developer Preview have undergone many changes in response to your feedback. Now it’s easier to add the controls to your app and the methods for hooking controls up to content are more intuitive. Some of the notable controls that have changed and will require you to make updates to are the ListView, AppBar, and FlipView. For example, you no longer can use an ArrayDataSource to populate a ListView. Instead, you now use a WinJS.Binding.List to populate your ListViews. Binding.List makes it much easier to work with your ListView’s in memory data.

Again, //Build to Windows 8 Consumer Preview has the full set of control changes.

Navigation within the top-level document

Previously, you could navigate within the top-level document of your app from the locally-packaged StartPage to a web-based URL. This prevented your app from interacting with any of the important notifications, such as suspend and resume, because these events are Windows Runtime events and, for security reasons, WinRT objects are inaccessible from the web context. In the Consumer Preview, you are no longer able to navigate to content other than that which is in the local context. In other words, it must come from your app package and be referenced via the ms-appx:// protocol scheme.

Consequently, you may need to reorganize your app logic to rely on an iframe for loading your web content, keeping a single persistent top-level document from the local context always in memory.

WinJS fragment loading and pages model

In the Developer Preview, the navigation model in HTML/CSS/JS Metro style apps relied on fragment loading APIs for navigating to different pages within an app. This model was fragile and forced you to write a lot of code to handle things like control initialization and page state.

In the Consumer Preview, we introduced a high-level page control in the Windows Library for JavaScript (WinJS) for loading content within a page. Additionally, we updated the Visual Studio templates to use these page controls. In most cases, page controls bypass the need to deal with the fragment loading APIs directly. This makes navigating across your HTML fragments much easier.

Page controls build on top of the fragment loader. They provide an actual object that backs rendered fragments, give you a place to store state, and handle parenting the fragment for you. There is a WinJS control backing your fragment—attached to the parented DOM element—which provides it with a well-defined lifecycle. You can also add arbitrary methods or state to this control object.

Termination of apps on unhandled exceptions

JavaScript is very tolerant of unhandled exceptions, stopping execution of any further code in the function containing the exception, but otherwise continuing on in a way that is often unnoticeable. When this happens, your app is no longer in a predictable state. This means that data that your app is relying on may not be valid, or your UI may end up in a broken state. In a web browser, this may be acceptable because the user can refresh the page. But, in a Metro style app, the user must be able to run your app for weeks without ever needing to close and reopen it.

As such, an unhandled JavaScript exception now logs an error message to the event log and terminates the app.

Important XAML Metro style app changes

If you have developed XAML Metro style apps, you’ll notice some changes in the Consumer Preview specific to your programming languages.

C++ Data Binding Support

In the Consumer Preview, we’ve made significant changes for C++ developers to make data binding XAML UI to custom C++ classes much simpler.  When you use annotation on your class via the Windows.UI.Xaml.Data.Bindable attribute, your class becomes visible to the binding engine and you no longer have to implement the interface on this class. This significantly reduces your code overhead.

Navigation API

If your XAML Metro style app uses navigation APIs, such as Windows.UI.Xaml.Controls.Frame.Navigate or Windows.UI.Xaml.Navigation.NavigationEventArgs.Type, you’ll need to make some quick changes. These APIs now accept a Type object as the target, rather than the string name representation of the class. Check out //Build to Windows 8 Consumer Preview for the full list of affected APIs.

AppBar

We made numerous changes to Windows.UI.Xaml.Controls.ApplicationBar functionality to make it more consistent with the user experience for Metro style apps. These changes also remove the overhead of you having to worry about implementation details to match the Metro style experience.

One major change is that you can place an AppBar within your app using the new Windows.UI.Xaml.Controls.Page.TopAppBar and BottomAppBar properties. We recommend that you use these new properties rather than placing your AppBars directly within your app’s layout. We added, renamed, or removed several other AppBar properties.

Semantic zoom

Semantic zoom is the term used across the Windows 8 platform when the user can zoom in or out on content and change its context. For example, zooming in on a collection of photos might change the photos from small thumbnails to large previews complete with names, dates, etc. The JumpViewer control enabled semantic zoom in the Developer Preview. It has been renamed to the SemanticZoom control. The new name better reflects the user experience that you provide when you implement one of these controls in your app.

Where to go from here

In addition to the changes called out in this post, many APIs in the Windows Runtime and the Windows Library for JavaScript have changed. For example in the Windows Runtime there are changes in the Networking, Media, System, UI, Storage, Devices, ApplicationModel, Globalization, Graphics, and Data namespaces. While many of these changes are minor, you’ll want to take care when migrating your code so that you make all the necessary changes in your app. This post is meant to get you started, but it only covers a small sample of the changes we’ve made to the development platform. As I suggested throughout the post take a look at //Build to Windows 8 Consumer Preview in the Dev Center to get detailed info on how to migrate your app to the Consumer Preview.

I look forward to your comments. If you have detailed “how do I …” questions I suggest you post them on the developer forums and we’ll be there to help you figure it out.

-- John Sheehan, Partner Architect, Windows Development