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!
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!)
- Create a new project in Visual Studio and pick the template that most closely resembles the UI of your existing app.
- 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.
- 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.
- 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.
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.
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.
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
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.
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.
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
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.
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.
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 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
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