Upload
others
View
5
Download
0
Embed Size (px)
Citation preview
Migrating your Windows 8 Consumer Preview
app to Windows 8 Release Preview
May 31, 2012
Abstract
This paper provides guidance and tips for migrating code assets built using the Windows 8
Consumer Preview released in February 2012 to the Windows 8 Release Preview. It includes
porting guidance, a change manifest, and helpful details for developers who are tasked with
migrating apps from the Windows 8 Consumer Preview. It assumes that the reader is familiar
with the Windows 8 Consumer Preview.
This information applies to the following operating systems:
Windows® 8 Release Preview
Windows Server® 2012
The current version of this paper is maintained on the web at:
http://go.microsoft.com/fwlink/?LinkId=251943
Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it.
Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.
This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.
© 2012 Microsoft. All rights reserved.
Microsoft, DirectX, Visual Basic, Visual Studio, Windows, and Windows Server are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —2
May 31, 2012
© 2012 Microsoft. All rights reserved.
Contents Introduction ........................................................................................................................................................................................................ 8
General porting guidance ............................................................................................................................................................................. 8
Visual Studio project recommendation ............................................................................................................................................. 9
WRL ........................................................................................................................................................................................................................ 9
Visual Studio projects and XAML templates ....................................................................................................................................... 10
Windows.UI.Xaml ...................................................................................................................................................................................... 10
Parameter name changes in a few XAML APIs ........................................................................................................................ 10
Windows.UI.Xaml.Automation ............................................................................................................................................................. 11
Unsealing AutomationPeer.GetPeerFromPoint and making it override able ............................................................. 11
Windows.UI.Xaml.Automation.Peers ................................................................................................................................................. 11
Changing AutomationControlType for SemanticZoom control ....................................................................................... 11
Windows.UI.Xaml.Controls .................................................................................................................................................................... 12
Frame.StopLoading has been deprecated ................................................................................................................................ 12
MediaPlayer control has been deprecated ............................................................................................................................... 12
Removing public constructor for OrientedVirtualizingPanel type .................................................................................. 13
Moving CarouselPanel to Windows.UI.Xaml.Controls.Primitives ..................................................................................... 13
Introducing new Auto ScrollMode ............................................................................................................................................... 14
Changing ScrollViewer's IsTabStop default to false .............................................................................................................. 15
Removing PreferIncrementalLoading property from ListViewBase ................................................................................ 16
Unsealing AppBar and sealing panels......................................................................................................................................... 17
WebView.AllowedScriptNotifyUris type change ..................................................................................................................... 17
Renaming MediaElement.Video3DMode to Stereo3DPackingMode ............................................................................ 18
Changing ToggleButton’s visual states ...................................................................................................................................... 18
Windows.UI.Xaml.Controls.Primitives ............................................................................................................................................... 19
Removing IScrollInfo, IItemContainerGenerator and IRecyclingItemContainerGenerator interfaces ............... 19
Windows.UI.Xaml.Controls, Windows.UI.Xaml.Navigation....................................................................................................... 19
WebView control Navigation updates ........................................................................................................................................ 19
Windows.UI.Xaml.Data ............................................................................................................................................................................ 20
Removing ISupportPlaceholder interface .................................................................................................................................. 20
Windows.UI.Xaml.Media.Imaging ...................................................................................................................................................... 21
Change in SurfaceImageSource base class ............................................................................................................................... 21
Windows.UI.Xaml.Input .......................................................................................................................................................................... 21
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —3
May 31, 2012
© 2012 Microsoft. All rights reserved.
Radian value to degrees for Rotation, Angular, DesiredDeceleration, DesiredRotation properties ................. 21
Only one active ISurfaceImageSourceNative::BeginDraw() operation allowed per device ................................... 22
Replacing Windows.UI.Xaml.Input.PointerEventArgs with Windows.UI.Xaml.Input.PointerRoutedEventArgs
.................................................................................................................................................................................................................... 22
Replacing Windows.UI.Xaml.Input.KeyEventArgs with Windows.UI.Xaml.Input.KeyRoutedEventArgs ............ 23
Windows.UI.Xaml.Media.Animation .................................................................................................................................................. 23
Renaming TapUp/TapDown Theme Animations .................................................................................................................... 23
Non-namespace changes ...................................................................................................................................................................... 24
Removing legacy VSM fallback to MouseOver, Selected and Dragging state ........................................................... 24
Changing names of system provided resources..................................................................................................................... 26
Changes to default AppBar MinHeight and ProgressRing MinWidth/MinHeight values...................................... 26
Parameter checks for required parameters and UI thread checks .................................................................................. 27
Removing support for clr-namespace construct in XAML ................................................................................................. 27
Windows Store ................................................................................................................................................................................................ 28
Windows.ApplicationModel.Store...................................................................................................................................................... 28
New method CurrentAppSimulator.ReloadSimulatorAsync .............................................................................................. 28
New and updated method to get signed receipts for purchases ................................................................................... 29
App manifest .................................................................................................................................................................................................... 31
Lock screen notifications and certain background tasks are now mutually required ............................................. 31
Language Requirement ..................................................................................................................................................................... 33
Impact ...................................................................................................................................................................................................... 33
App manifest (minor) breaking changes ................................................................................................................................... 34
HTML5/CSS/JavaScript ................................................................................................................................................................................. 37
requestAnimationFrame API ........................................................................................................................................................... 37
IndexedDB numeric constants have been removed ............................................................................................................. 40
Fixing your code ................................................................................................................................................................................... 41
CSS Flexbox: moving to latest W3C syntax ............................................................................................................................... 41
Un-prefixed versions of web performance, CSS transitions, and CSS animations, and font features settings
APIs now available .............................................................................................................................................................................. 44
HTML Views: Scrollboundaries act as a limit on scrollLeft/scrollTop ............................................................................. 48
Update to getClientRects, getBoundingClientRects, and offsetLeft, offsetTop, width, and height ................... 48
Updating backface-visibility to latest CSS3 spec .................................................................................................................... 49
COM interfaces for SVG Filters have been removed............................................................................................................. 49
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —4
May 31, 2012
© 2012 Microsoft. All rights reserved.
SafeHTML validation for inline event handlers on unattached elements .................................................................... 50
Change to CSS3 property transform-origin ............................................................................................................................. 51
CSS animations and transitions with display:none no longer runs ................................................................................. 52
HTML Views: msSetPointerCapture no longer triggers manipulations ......................................................................... 52
HTML Touch Views: Changing coordinate space for RTL boundaries/snap-points and renaming -ms-scroll-
boundary-* APIs ................................................................................................................................................................................... 53
UTF-8 encoding with byte-order mark required for Windows Store onboarding ................................................... 54
Default context menus have been removed from HTML media elements .................................................................. 55
Remove default error page for top-level document navigation errors in Metro style apps using JavaScript
and HTML ............................................................................................................................................................................................... 56
Improved error handling .................................................................................................................................................................. 57
WinJS.UI.optionsParser no longer defaults to using "global" context........................................................................... 57
Removal of reveal and hide PVL animations from Windows Library for JavaScript (WinJS) ................................ 58
WinJS.Fragment.render and WinJS.UI.Pages.get only support “same context” access .......................................... 58
Tweak to JavaScript camel-casing rules ..................................................................................................................................... 58
‘name’ property of promise cancellation error objects now ‘Canceled’ ....................................................................... 59
JavaScript exceptions returned to Windows Runtime treated as unhandled ............................................................. 60
window.MSPointerEvent ........................................................................................................................................................................ 61
MSGestureStart, MSGestureChange and MSGestureEnd require additional developer setup work ................ 61
MSGestureTap and MSGestureHold require additional developer setup work ........................................................ 63
MSGesture transforms now report delta transforms ............................................................................................................ 64
Limiting msReleasePointerCapture DOM API to the current markup ........................................................................... 65
Deprecating DOM event method getPointerList ................................................................................................................... 65
Deprecating MSGestureDoubleTap ............................................................................................................................................. 65
Deprecating msGetPointerCapture DOM API .......................................................................................................................... 66
Deprecating MSPointerXXX.preventMouseEvents() .............................................................................................................. 67
New “isPrimary” property on MSPointer events (impacts use of initPointerEvent method) ................................ 68
Syntax .................................................................................................................................................................................................... 68
Parameters .......................................................................................................................................................................................... 69
.NET ...................................................................................................................................................................................................................... 70
Blocking dynamic invocation of nonpublic members in Metro style apps ................................................................. 70
[WinMDExp] Use WriteOnlyArray/readOnlyArray for arrays and blocks usage of In/Out for other cases ..... 71
[WinMDExp] Two minor breaking changes .............................................................................................................................. 73
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —5
May 31, 2012
© 2012 Microsoft. All rights reserved.
Reduce the .NET surface area to remove unnecessary access points to memory .................................................... 73
.NET Core Profile (Metro style apps) API changes ................................................................................................................. 75
Hide IPropertyValue and IReferenceArry<T> .......................................................................................................................... 75
Visual C++ ......................................................................................................................................................................................................... 76
Platform::Array^ input parameters need to be marked as const .................................................................................... 76
Protected fields are not permitted on ref classes .................................................................................................................. 77
Nested types are not permitted in private ref classes .......................................................................................................... 78
Virtual methods need to be explicitly specified as ‘virtual’ (and ‘override’ if needed) ........................................... 78
Non-Windows Runtime C++ exceptions will fail-fast when reaching the language boundary (rather than
turning into E_FAIL) ............................................................................................................................................................................ 79
Public ref classes need to be marked as either ‘sealed’ or have a non-public constructor .................................. 80
Newslot methods are not allowed in interface classes or ref classes (either implicitly or explicitly by using
the ‘new’ keyword) .............................................................................................................................................................................. 81
Private/internal ref classes need to follow the same authoring restrictions as public ref classes ..................... 81
Instances of types with the marshaling behavior != Agile used as field or global will issue a warning
recommending use of Platform::Agile<T> ............................................................................................................................... 82
Public templated ref classes, its explicit instantiations and public templated methods are not supported . 83
Can no longer derive from Platform::Exception ...................................................................................................................... 84
Explicit [Windows::Foundation::Metadata::Guid] attribute cannot be specified anymore on interfaces or
classes (only [uuid] is legal) ............................................................................................................................................................. 84
Graphics & Gaming ....................................................................................................................................................................................... 86
DirectXMath ........................................................................................................................................................................................... 86
Windows Parental Controls and Game Definition Files (GDF) .......................................................................................... 87
COM ..................................................................................................................................................................................................................... 89
CoWaitForMultipleHandles function and CoWait_Flags ..................................................................................................... 89
Namespaces ..................................................................................................................................................................................................... 90
Windows.ApplicationModel.Resources.Core ................................................................................................................................. 90
toString, toFileAsync rename .......................................................................................................................................................... 90
Windows.Devices.Sms ............................................................................................................................................................................. 91
Windows.Foundation.Collections ....................................................................................................................................................... 91
PropertySet marshaling behavior is changing from non-agile to agile ........................................................................ 91
Windows.Globalization ........................................................................................................................................................................... 91
ApplicationPreferences removed .................................................................................................................................................. 91
Calendar.Compare method ............................................................................................................................................................. 93
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —6
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.Globalization.Fonts ............................................................................................................................................................... 94
LanguageFontGroup property changes ..................................................................................................................................... 94
Windows.Graphics.Printing ................................................................................................................................................................... 96
IPrintDocumentPackageTargetFactory and IPrintDocumentPackageStatusEvent are not accessible to Metro
style apps ................................................................................................................................................................................................ 96
Additional parameter to pass while creating DXGI surface for printing ....................................................................... 97
CMetroTemplatePrinter object to call StartPrint() method ................................................................................................ 98
Windows.Management.Deployment ................................................................................................................................................ 99
(Minor) Breaking change and new additions to Package Manager Inventory APIs ................................................. 99
Windows.Networking.BackgroundTransfer ................................................................................................................................. 101
Windows.Networking.BackgroundTransfer API updates ................................................................................................. 101
Windows.Networking.NetworkOperators .................................................................................................................................... 102
Service metadata changes ............................................................................................................................................................ 102
Provisioning metadata changes ................................................................................................................................................. 104
Windows.Networking.Proximity ....................................................................................................................................................... 108
Windows.Networking.Proximity.PeerFinder renames ........................................................................................................ 108
Windows.Networking.Sockets .......................................................................................................................................................... 108
Windows.Networking.Sockets property name changes ................................................................................................... 108
Windows.security.authentication.OnlineId .................................................................................................................................. 111
Moving to IIterable and removal of caption from API ...................................................................................................... 111
Windows.Storage ................................................................................................................................................................................... 112
Default collision option change for file create in StorageFolder and DownloadsFolder .................................... 112
Transacted streams and CreateFileAsync options............................................................................................................... 113
Windows.Storage.ApplicationData ................................................................................................................................................. 116
Changes to IApplicationData::SetVersionAsync exception handling .......................................................................... 116
Removal of IApplicationData::get_RoamingStorageUsage() .......................................................................................... 116
Windows.Storage.Streams ................................................................................................................................................................. 117
DataReader::DetachStream and DataWriter::DetachStream will fail ............................................................................ 117
Windows.System .................................................................................................................................................................................... 117
New restrictions on the protocols that Metro style apps can launch and register for ........................................ 117
Windows.System.UserProfile.UserInformation .......................................................................................................................... 120
Converted getting user names to asynchronous methods ............................................................................................. 120
Samples ................................................................................................................................................................................................ 120
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —7
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.UI.Core.CoreWindow ........................................................................................................................................................ 121
Close method now fails when called on main window ..................................................................................................... 121
ICoreWindowPopupShowingEventArgs .................................................................................................................................. 121
Deprecation of Invoke and InvokeAsync methods and addition of RunAsync ....................................................... 123
IInternalCoreWindow interface moved to private .............................................................................................................. 123
Method calls on a proxy CoreWindow will fail even if the object is smuggled back to the UI thread ......... 124
Windows.UI.Input ................................................................................................................................................................................... 125
Additional API support for mouse button transitions in IPointerPointProperties ................................................. 125
Changes in swipe and translation deltas ................................................................................................................................ 126
Windows.UI.Input.Inking ..................................................................................................................................................................... 128
Ink API will now return a vector of runtime classes instead of a vector of appropriate interfaces ................ 128
Windows.UI.Notifications ................................................................................................................................................................... 129
Query strings for tile/toast notifications not appended by default ............................................................................. 129
Windows.UI.ViewManagement ........................................................................................................................................................ 131
ViewStateChanged event removed ........................................................................................................................................... 131
Windows.Web.Syndication................................................................................................................................................................. 133
Windows.Web.Syndication property name changes ......................................................................................................... 133
Remove ToString method from ISyndicationText ............................................................................................................... 133
Appendix: Summary of API name changes ...................................................................................................................................... 135
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —8
May 31, 2012
© 2012 Microsoft. All rights reserved.
Introduction
Welcome to the guide for migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview.
This document helps developers who have written apps or samples that worked with Windows 8 Consumer
Preview and who now must update their Metro style apps to work with the Windows 8 Release Preview. A lot
has changed since February 2012!
The goal of this guide is not to provide an exhaustive list of breaking changes or potential issues, but rather
point out the most relevant “gotchas.” This should save you time, and get you to “80%” much faster than you
would have gotten there otherwise. There are also descriptions of some of the new features in the Windows 8
Release Preview.
At the time of writing, the Windows 8 Release Preview was not available in its final form. As such, this guide
may contain inaccuracies or inconsistencies.
General porting guidance
Although we have worked hard to keep churn and breaking changes to a minimum since the Consumer
Preview, it was inevitable that we would have to make some changes to enhance the developer experience and
to have a clear and consistent API surface. Because version 1 of an API surface like the Windows Runtime is a
huge commitment, we wanted to make sure that any breaking changes were made with the right trade-offs
between developer pain and long-term benefits in mind.
This document offers tips for getting up and running as fast as possible as you migrate your apps from the the
Consumer Preview to the Release Preview. The information is organized first under high-level headings (like
Visual Studio®
projects, Windows Store changes, App manifest changes) and then by low-level categories like
individual Windows Runtime namespaces.
Here are the high-level steps for migrating your app from the Windows 8 Consumer Preview to the Release
Preview:
Step 1 – Migrate your Microsoft Visual Studio project.
Step 2 – Migrate your app manifest.
Step 3 – Fix compiler errors caused by the breaking changes, by referring to this document.
Step 4 – Review breaking changes in the namespaces that you use and make updates as necessary.
Step 5 - Review the Windows Store API changes and make updates as needed.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —9
May 31, 2012
© 2012 Microsoft. All rights reserved.
Visual Studio project recommendation
There have been nontrivial changes to the XAML and Visual Studio templates (StandardStyles.xaml and VS
project templates), so we recommend that you start over with new projects. This will involve creating a new VS
project for your app from latest preliminary Microsoft Visual Studio release that comes with Windows 8 Release
Preview, which will generate the new XAML templates.
Following are the details of all breaking changes that resulted in the preceding recommendation.
WRL
The __WRL_STRICT__ flag is turned on now, which adds extra validation. The following are the scenarios in
which it adds more compile-time checks:
1. Force users to use the InspectableClass macro since the Runtime class will not provide implementation for
GetRuntimeClassName and GetTrustLevel
2. Add strict verification for RuntimeClass template parameters:
a. No possibility to use the IUnknown interface unless it’s the first template parameter.
b. No possibility impacto use the IInspectable interface unless it’s the first template parameter.
c. Force developers to respect RuntimeClassFlags -> WinRt can be used with WinRt, ClassicCom can
be only used with ClassicCom, WinRtMix can be used with both.
d. Verifies that SimpleActivationFactory can create WinRt interface and not ClassicCom.
e. Verifies that SimpleClassFactory can create ClassicCom interface and not WinRt.
Who is impacted:
Sample developers and teams external to Windows.
Action to take:
Samples authors whose samples that fail to compile must fix their usage.
Teams external to Windows may work around this issue using the __WRL_CONFIGURATION_LEGACY__ flag,
which Windows uses to avoid the stronger validation.
The following error may occur:
error C2338: 'I' has to derive from 'IUnknown' and must not be IUnknown and/or IInspectable.
If you receive this error, make sure that your interface is not IUnknown and is not IInspectable. When using
WinRtClassicComMix, make sure that the first RuntimeClass template parameter is IInspectable based.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —10
May 31, 2012
© 2012 Microsoft. All rights reserved.
Visual Studio projects and XAML templates
Windows.UI.Xaml
Parameter name changes in a few XAML APIs
Brief description:
The return value parameter names in the following API’s have been changed from the generic “property” to
more relevant names in order to avoid using reserved keywords:
Before Changed to
HRESULT Register([in] HSTRING name, [in]
Windows.UI.Xaml.Interop.TypeName propertyType, [in]
Windows.UI.Xaml.Interop.TypeName ownerType, [in]
PropertyMetadata* typeMetadata, [out, retval]
DependencyProperty** property);
HRESULT Register([in] HSTRING name, [in]
Windows.UI.Xaml.Interop.TypeName propertyType, [in]
Windows.UI.Xaml.Interop.TypeName ownerType, [in]
PropertyMetadata* typeMetadata, [out, retval]
DependencyProperty** dependencyProperty);
HRESULT RegisterAttached([in] HSTRING name, [in]
Windows.UI.Xaml.Interop.TypeName propertyType, [in]
Windows.UI.Xaml.Interop.TypeName ownerType, [in]
PropertyMetadata* defaultMetadata, [out, retval]
DependencyProperty** property);
HRESULT RegisterAttached([in] HSTRING name, [in]
Windows.UI.Xaml.Interop.TypeName propertyType, [in]
Windows.UI.Xaml.Interop.TypeName ownerType, [in]
PropertyMetadata* defaultMetadata, [out, retval]
DependencyProperty** dependencyProperty);
HRESULT RaisePropertyChangedEvent([in]
Windows.UI.Xaml.Automation.AutomationProperty*
property, [in] IInspectable* oldValue, [in] IInspectable*
newValue);
HRESULT RaisePropertyChangedEvent([in]
Windows.UI.Xaml.Automation.AutomationProperty*
automationProperty, [in] IInspectable* oldValue, [in]
IInspectable* newValue);
HRESULT FindItemByProperty([in]
Windows.UI.Xaml.Automation.Provider.IRawElementProvi
derSimple* startAfter, [in]
Windows.UI.Xaml.Automation.AutomationProperty*
property, [in] IInspectable* value, [out, retval]
Windows.UI.Xaml.Automation.Provider.IRawElementProvi
derSimple** returnValue);
HRESULT FindItemByProperty([in]
Windows.UI.Xaml.Automation.Provider.IRawElementProvi
derSimple* startAfter, [in]
Windows.UI.Xaml.Automation.AutomationProperty*
automationProperty, [in] IInspectable* value, [out,
retval]
Windows.UI.Xaml.Automation.Provider.IRawElementProvi
derSimple** returnValue);
HRESULT GetCustomProperty([in] HSTRING name, [out,
retval] ICustomProperty **property);
HRESULT GetCustomProperty([in] HSTRING name, [out,
retval] ICustomProperty **customProperty);
HRESULT GetIndexedProperty([in] HSTRING name, [in]
Windows.UI.Xaml.Interop.TypeName type, [out, retval]
ICustomProperty **property);
HRESULT GetIndexedProperty([in] HSTRING name, [in]
Windows.UI.Xaml.Interop.TypeName type, [out, retval]
ICustomProperty **customProperty);
Languages C#, C++
Issue and details Any code that used the above API’s in the following format will need to change
to use the new names:
MethodName(property: myProperty, …)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —11
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples usage or steps
to take to migrate code
Example:
RaisePropertyChangedEvent(property: myProperty, …)
Must now be changed to
RaisePropertyChangedEvent(automationProperty: myProperty, …)
Windows.UI.Xaml.Automation
Unsealing AutomationPeer.GetPeerFromPoint and making it override able
Brief description:
The GetPeerFromPoint event has been unsealed and a new overrideable API GetPeerFromPointCore has been
added to AutomationPeer in order to enable app authors to support ElementFromPoint for Custom controls.
Languages C#, C++
Windows.UI.Xaml.Automation.Peers
Changing AutomationControlType for SemanticZoom control
Brief description:
The AutomationPeer.AutomationControlType for SemanticZoom control has been changed from “Custom” to
“SemanticZoom”.
Languages C#, C++
Issue and details If your automation test cases were expecting SemanticZoom control to return a
AutomationControlType of “Custom”, these will be broken.
Samples usage or steps
to take to migrate code
Any reference to SemanticZoom control’s AutomationControlType must be
changed from “Custom” to “SemanticZoom”.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —12
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.UI.Xaml.Controls
Frame.StopLoading has been deprecated
Brief description:
Frame.StopLoading was designed to stop async Frame navigations. However Frame navigations are always
synchronous, so Frame.StopLoading has been removed.
Languages C#, C++
Issue and details Compilation will fail with an error similar to the following:
Samples usage
or steps to take
to migrate code
Remove any instances of Frame.StopNavigation()
MediaPlayer control has been deprecated
Brief description:
MediaPlayer control has been deprecated from the XAML framework for Windows 8. Moving forward, all media
scenarios must utilize the MediaElement API.
Languages C#, C++
Issue and details If your app uses a MediaPlayer control, errors similar to the following will occur:
Samples usage or steps to
take to migrate code
Remove any instances of MediaPlayer control and replace them with
MediaElement API. Building transport controls around MediaElement control is
explained in detail in the BasicMediaPlayback SDK sample available with Windows
SDK.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —13
May 31, 2012
© 2012 Microsoft. All rights reserved.
You can also refer to http://playerframework.codeplex.com for a full end to end
solution to support multiple features including CC and IIS smooth streaming.
Removing public constructor for OrientedVirtualizingPanel type
Brief description:
The public constructor for OrientedVirtualizingPanel type has been removed so this type cannot be instantiated
anymore.
Languages C#, C++
Issue and details If your app tries to instantiate OrientedVirtualizingPanel, errors similar to the
following will occur:
Samples usage or steps
to take to migrate code
Use VirtualizingStackPanel or WrapGrid instead of OrientedVirtualizingPanel
Moving CarouselPanel to Windows.UI.Xaml.Controls.Primitives
Brief description:
The CarouselPanel control is being moved to Windows.UI.Xaml.Controls.Primitives from
Windows.UI.Xaml.Controls. This type is used as part of ComboBox and not meant to be used independently.
Languages C#, C++
Issue and details If your app contains CarouselPanel but does not use
Windows.UI.Xaml.Controls.Primitives, the following errors will occur:
Samples usage or steps
to take to migrate code
Replace any instance of Windows.UI.Xaml.Controls.CarouselPanel with
Windows.UI.Xaml.Controls.Primitives.CarouselPanel
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —14
May 31, 2012
© 2012 Microsoft. All rights reserved.
Introducing new Auto ScrollMode
Brief description:
1. A new ScrollMode – “Auto” - has been introduced to not show overscroll bounce in the direction that
has been configured if the content fits the viewport. For example, if HorizontalScrollMode=”Auto” and
if the content is zoomed in small enough to completely fit inside the viewport horizontally, there will
be no overscroll bounce effect when the user tries to pan the content in the horizontal direction. If the
content is zoomed in to become bigger than the viewport, panning in horizontal direction will be
automatically enabled.
2. The ScrollMode for “Rails” has been moved to a separate property in ScrollViewer. App authors can
now disable/enable rails along horizontal/vertical direction independent of ScrollMode being
Enabled/Auto. When ScrollMode is Disabled, however, enabling/disabling of rails is irrelevant.
Based on the above changes:
1. ScrollViewer.HorizontalScrollMode and ScrollViewer.VerticalScrollMode now have the following
valid settings:
Enabled
Disabled
Auto
2. ScrollViewer has the following new properties:
IsHorizontalRailEnabled
IsVerticalRailEnabled
3. The default behavior is exactly the same as old defaults. That is, Rails has been retained as the
default ScrollViewer experience.
Languages C#, C++
Issue and details If your XAML code sets HorizontalScrollMode and/or VerticalScrollMode =
“Rails”, a runtime exception as shown below will occur and the app will crash:
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —15
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples usage or steps
to take to migrate code
Any references to ScrollMode.Rails have to be changed to use the new
properties.
For example:
<ScrollViewer HorizontalScrollMode="Rails" … />
Must be changed to:
<ScrollViewer HorizontalScrollMode="Enabled"
IsHorizontalRailEnabled="True" … />
Changing ScrollViewer's IsTabStop default to false
Brief description:
ScrollViewer's IsTabStop default value has been changed from True to False. This will impact apps that have
content in a ScrollViewer that cannot receive focus (like Image Control). This change was made in order to cater
to the scenario of moving focus to the content inside a ScrollViewer instead of the ScrollViewer itself. This was
found to be a more common scenario than tabbing to the ScrollViewer and hence the default has been
switched to false. This was exasperated by the fact that ScrollViewer does not provide a default focus visual.
Languages C#, C++
Issue and details No errors will be occurring. This is a behavioral breaking change.
Samples usage or steps
to take to migrate code
Apps that have content that can get focus inside a ScrollViewer will not need to
change their code. If your app contains a ScrollViewer with only non Control
elements like Image, VSIS etc., the following change needs to be made:
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —16
May 31, 2012
© 2012 Microsoft. All rights reserved.
Before Now
<ScrollViewer ... >
<my non focusable content>
</ScrollViewer>
<ScrollViewer IsTabStop=”True” ... >
<my non focusable content>
</ScrollViewer>
Removing PreferIncrementalLoading property from ListViewBase
Brief description:
PreferIncrementalLoading property on ListViewBase has been removed. Data interface
ISupportIncrementalLoading is available for virtualizing data. Classic (or random access) virtualization can be
achieved by using IObservableVector or INotifyCollectionChanged interfaces and can be used in conjunction
with ISupportIncrementalLoading.
Languages C#, C++
Issue and details If your app references PreferIncrementalLoading within GridView and/or ListView
controls, errors similar to the following will occur:
Samples usage or
steps to take to
migrate code
Any reference to PreferIncrementalLoading has to be removed.
For example:
<GridView PreferIncrementalLoading="True" /> <ListView PreferIncrementalLoading="False" />
Can no longer be used.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —17
May 31, 2012
© 2012 Microsoft. All rights reserved.
Unsealing AppBar and sealing panels
Brief description:
AppBar control has been unsealed in order to enable other Edge UI behavior. VirtualizingPanel,
VirtualizingStackPanel and OrientedVirtualizingPanel controls have been sealed since they are not meant to be
extended.
Languages C#, C++
Issue and details If your custom control extends VirtualizingPanel, VirtualizingStackPanel or
OrientedVirtualizingPanel, you will encounter build errors as shown below:
Samples usage or steps
to take to migrate code
Any extensions of VirtualizingPanel, VirtualizingStackPanel or
OrientedVirtualizingPanel need to be removed.
For example:
public class UserControl1 : VirtualizingPanel
needs to be removed.
WebView.AllowedScriptNotifyUris type change
Brief description:
The WebView.AllowedScriptNotifyUris property has changed type from IIterable to IVector. This will now return
an empty collection instead of returning NULL as a default. This makes it easier for app developers to simply
add entries to the collection.
Languages C#, C++
Issue and details
Samples usage or steps
to take to migrate code
Any reference to AllowedScriptNotifyUris must be changed from defining using
IIterable to IVector.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —18
May 31, 2012
© 2012 Microsoft. All rights reserved.
Renaming MediaElement.Video3DMode to Stereo3DPackingMode
Brief description:
Video3DMode API on MediaElement Control has been renamed to Stereo3DVideoPackingMode.
Stereo3DVideoRenderMode property is also being introduced to match the app building experience for
JavaScript apps media developers. Stereo3DVideoRenderMode will have “Mono” and “Stereo” as the available
options.
Languages C#, C++
Issue and details If your app references Video3DMode, the following errors will occur:
Samples usage or steps
to take to migrate code
Any reference to Video3DMode must be changed to
Stereo3DVideoPackingMode.
For Example:
<MediaElement Video3DMode="None" />
Must be changed to:
<MediaElement Stereo3DVideoPackingMode="None" />
Changing ToggleButton’s visual states
Brief description:
ToggleButton VisualStates have been changed. The following are the new VisualStates for ToggleButtons:
Normal, PointerOver, Pressed, Disabled,
Checked, CheckedPointerOver, CheckedPressed, CheckedDisabled,
Indeterminate, IndeterminatePointerOver, IndeterminatePressed, IndeterminateDisabled
Languages C#, C++
Issue and details
Samples usage or steps
to take to migrate code
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —19
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.UI.Xaml.Controls.Primitives
Removing IScrollInfo, IItemContainerGenerator and IRecyclingItemContainerGenerator
interfaces
Brief description:
IScrollInfo, IItemContainerGenerator and IRecyclingItemContainerGenerator interfaces have been removed from
XAML since these interfaces are not useful in their current shape to be consumed by 3rd
party panels. However,
the properties, methods and events (PME) of the interface are now on the types that implemented them. All
API’s that existed in IScrollInfo have now been added to ScrollContentPresenter, OrientedVirtualizingPanel and
CarouselPanel classes.
Languages C#, C++
Issue and details If your class implements IScrollInfo, IItemContainerGenerator and/or
IRecyclingItemContainerGenerator, the following build errors will occur:
Samples usage or steps
to take to migrate code
Any references to IScrollInfo, IItemContainerGenerator and
IRecyclingItemContainerGenerator have to be removed. Instead of implementing
these interfaces, you can directly extend one of the 3 classes
(ScrollContentPresenter, OrientedVirtualizingPanel or CarouselPanel) as the need
may be and inherit the methods and properties.
Windows.UI.Xaml.Controls, Windows.UI.Xaml.Navigation
WebView control Navigation updates
Brief description:
Developers using the WebView control had no way to know if a particular navigation failed. The typical pattern
was to issue a navigation request via the WebView.Navigate() method and then hook the
WebView.LoadCompleted event to know when the page was successfully loaded. If the navigation failed, they
received no indication and would continue to wait for the LoadCompleted event to fire, which it never would.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —20
May 31, 2012
© 2012 Microsoft. All rights reserved.
The WebView control now supports reporting of navigation errors. NavigationFailed event has been added to
WebView control which will be fired whenever there is a navigation error. This event uses a new event arg
called WebViewNavigationFailedEventArgs which has WebErrorStatus and Uri properties.
As part of this change INavigatingCancelEventArgsFactory, INavigationFailedEventArgsFactory and
INavigationEventArgsFactory interfaces have also been removed since they were not being used.
Languages C#, C++
Issue and details If your app references NavigatingCancelEventArgs, NavigationFailedEventArgs
and/or NavigationEventArgs, build errors will occur that the type/namespace
could not be found.
Samples usage or steps
to take to migrate code
Any references to NavigatingCancelEventArgs, NavigationFailedEventArgs and
NavigationEventArgs have to be removed.
Windows.UI.Xaml.Data
Removing ISupportPlaceholder interface
Brief description:
The ISupportPlaceholder interface has been removed. All XAML Controls have been modified to support
null/nullptr as the value that will trigger the Placeholder VisualState.
Languages C#, C++
Issue and details If your class implements ISupportPlaceholder interface, build errors similar to the
following will occur:
Samples usage or steps
to take to migrate code
Workaround is to remove implementations of this interface and return null/nullptr for
placeholders.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —21
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.UI.Xaml.Media.Imaging
Change in SurfaceImageSource base class
SurfaceImageSource runtime class used to inherit from Windows.UI.Xaml.Media.BitmapSource. The change is
that now it inherits from Windows.UI.Xaml.Media.ImageSource which BitmapSource inherits from.
Windows.UI.Xaml.Input
Radian value to degrees for Rotation, Angular, DesiredDeceleration, DesiredRotation
properties
Brief description:
Radian value to degrees for Rotation, Angular, DesiredDeceleration, DesiredRotation properties.
Properties Old New
Windows.UI.Xaml.Input.ManipulationStartedRoutedEventArgs.
Cumulative.Rotation
Radian Degrees
Windows.UI.Xaml.Input.ManipulationDeltaRoutedEventArgs.
Delta.Rotation
Radian Degrees
Windows.UI.Xaml.Input.ManipulationDeltaRoutedEventArgs.
Cumulative.Rotation
Radian Degrees
Windows.UI.Xaml.Input.ManipulationDeltaRoutedEventArgs.
Velocities. Angular
Radian Degrees
Windows.UI.Xaml.Input.ManipulationCompletedRoutedEventArgs.
Cumulative.Rotation
Radian Degrees
Windows.UI.Xaml.Input.ManipulationCompletedRoutedEventArgs.
Velocities. Angular
Radian Degrees
Windows.UI.Xaml.Input.ManipulationInertiaStartingRoutedEventArgs.
Cumulative.Rotation
Radian Degrees
Windows.UI.Xaml.Input.ManipulationInertiaStartingRoutedEventArgs.
Velocities. Angular
Radian Degrees
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —22
May 31, 2012
© 2012 Microsoft. All rights reserved.
Properties Old New
Windows.UI.Xaml.Input.ManipulationInertiaStartingRoutedEventArgs.
RotationBehavior.DesiredDeceleration
Radian Degrees
Windows.UI.Xaml.Input.ManipulationInertiaStartingRoutedEventArgs.
RotationBehavior.DesiredRotation
Radian Degrees
Impact
Replace the degrees value from radian for above property usage.
Only one active ISurfaceImageSourceNative::BeginDraw() operation allowed per device
What’s changing?
By default, a XAML SurfaceImageSource or VirtualSurfaceImageSource will now allow only one active
BeginDraw() operation at a time per IDXGIDevice. Previously, one active BeginDraw() was allowed per
SurfaceImageSource/VirtualSurfaceImageSource. Further restricting this API enables additional performance
optimization. In practice this means that once ISurfaceImageSourceNative::BeginDraw() has been called on a
SurfaceImageSource associated with a given device, an app must now call
ISurfaceImageSourceNative::EndDraw() before it can call BeginDraw() again.
Impact / Required Action
Any app using a SurfaceImageSource or VirtualSurfaceImageSource that calls
ISurfaceImageSourceNative::BeginDraw() multiple times per device before calling EndDraw() must be modified
to instead call EndDraw() after each BeginDraw() call.
Replacing Windows.UI.Xaml.Input.PointerEventArgs with
Windows.UI.Xaml.Input.PointerRoutedEventArgs
Brief description:
Windows.UI.Xaml.Input.PointerEventArgs is being replaced with
Windows.UI.Xaml.Input.PointerRoutedEventArgs in order to avoid conflict with
Windows.UI.Input.PointerEventArgs
Languages C#, C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —23
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and details If your app references PointerEventArgs, the following errors will occur:
Samples usage or
steps to take to
migrate code
Replace any instance of Windows.UI.Xaml.Input.PointerEventArgs with
Windows.UI.Xaml.Input.PointerRoutedEventArgs
Replacing Windows.UI.Xaml.Input.KeyEventArgs with
Windows.UI.Xaml.Input.KeyRoutedEventArgs
Brief description:
Windows.UI.Xaml.Input.KeyEventArgs is being replaced with Windows.UI.Xaml.Input.KeyRoutedEventArgs in
order to avoid conflict with Windows.UI.Input.KeyEventArgs
Languages C#, C++
Issue and details If your app references KeyEventArgs, the following errors will occur:
Samples usage or steps
to take to migrate code
Replace any instance of Windows.UI.Xaml.Input.KeyEventArgs with
Windows.UI.Xaml.Input.KeyRoutedEventArgs
Windows.UI.Xaml.Media.Animation
Renaming TapUp/TapDown Theme Animations
Brief description:
In order to be consistent with PVL animation names, the following changes have been made:
1. TapUpThemeAnimation has been changed to PointerUpThemeAnimation
2. TapDownThemeAnimation has been changed to PointerDownThemeAnimation
Languages C#, C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —24
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and details If your app references TapUpThemeAnimation and/or TapDownThemeAnimation, the
following errors will occur:
Samples usage or
steps to take to
migrate code
Any reference to TapUpThemeAnimation and/or TapDownThemeAnimation must be
changed to PointerUpThemeAnimation and/or PointerDownThemeAnimation.
For example:
<Storyboard x:Name="tapstoryboard"> <TapUpThemeAnimation … /> <TapDownThemeAnimation … /> </Storyboard>
Must be changed to:
<Storyboard x:Name="tapstoryboard"> <PointerUpThemeAnimation … /> <PointerDownThemeAnimation … /> </Storyboard>
Non-namespace changes
Removing legacy VSM fallback to MouseOver, Selected and Dragging state
Brief description:
VSM states for Selection were added newly in Windows 8 XAML during Consumer Preview. For PointerOver the
fallback code for MouseOver was retained to not break existing apps or legacy XAML from Silverlight. This is
now being deprecated. To be consistent, the VSM fallback for the Dragging state in GridView/ListView when a
MultipleDraggingPrimary state is not present is also being deprecated.
The following table lists the before and after state names:
Before Now
<VisualStateGroup
x:Name="CommonStates">
<VisualState x:Name=”MouseOver”>
<VisualStateGroup
x:Name="CommonStates">
<VisualState x:Name=”PointerOver”>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —25
May 31, 2012
© 2012 Microsoft. All rights reserved.
Before Now
…
</VisualState>
</VisualStateGroup>
…
</VisualState>
</VisualStateGroup>
<VisualStateGroup
x:Name="SelectionStates">
<VisualState x:Name=”Selected”>
…
</VisualState>
</VisualStateGroup>
<VisualStateGroup
x:Name="SelectionStates">
<VisualState
x:Name=”SelectedUnfocused”>
…
</VisualState>
</VisualStateGroup>
<VisualStateGroup
x:Name="DragStates">
<VisualState x:Name=”Dragging”>
…
</VisualState>
</VisualStateGroup>
<VisualStateGroup
x:Name="DragStates">
<VisualState
x:Name=”MultipleDraggingPrimary”>
…
</VisualState>
</VisualStateGroup>
Languages C#, C++
Issue and details
Samples usage or steps
to take to migrate code
Replace any instance of MouseOver with PointerOver etc.,
For example:
VisualStateManager.GoToState(this, "MouseOver", true);
Must be changed to:
VisualStateManager.GoToState(this, "PointerOver", true);
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —26
May 31, 2012
© 2012 Microsoft. All rights reserved.
Changing names of system provided resources
Brief description:
All Resources (brushes, metrics) provided by the runtime, referred to as "theme resources", have names
changed and in some cases removed. These resources are brushes and metrics that are used (directly or
indirectly via project templates) in XAML {StaticResource resourceName} lookups. The actual name changes can
be found in the following table:
Appendix: Summary of API name changes
Languages C#, C++
Issue and details If your app has a reference to one of more the theme resources from the above list
(either through Visual Studio Project Template or through your own Control
Template), the following errors will occur:
Samples usage or steps
to take to migrate code
Replace your usage with the updated name from the above list.
For example:
<Grid Background="{StaticResource ApplicationPageBackgroundBrush}">
Must be changed to:
<Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">
Changes to default AppBar MinHeight and ProgressRing MinWidth/MinHeight values
Brief description:
XAML AppBar control’s default MinHeight value has been changed from 68 to 88. XAML ProgressRing control’s
default MinHeight and MinWidth have been changed from 60 to 20.
Languages C#, C++
Issue and details If your app was relying on the defaults to set up Width and Height of Appbar
and ProgressRing controls, your visual effect will now be changed considerably.
Samples usage or steps
to take to migrate code
You can retain the default visual experience by manually setting the width and
height to previous defaults.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —27
May 31, 2012
© 2012 Microsoft. All rights reserved.
For example:
<ProgressRing .../>
can be changed to:
<ProgressRing Width=”60” Height=”60” />
if you want to retain your previous visual experience.
Parameter checks for required parameters and UI thread checks
Brief description:
Two new types of checks have been added to all XAML Public API’s:
1. UI Thread check: XAML will throw when API’s are accessed from threads other than UI Threads.
2. Null checks for parameters: E_INVALIDARG (ArgumentException) will be raised with information
on which parameter was invalid when passing in an invalid parameter or setting an invalid
property that is required
Languages C#, C++
Issue and details If an app was calling an API from a non-UI thread and that API didn’t already do a
thread-check, it may have failed unexpectedly before. With this change, it will fail
consistently and predictably.
If an app was previously passing in NULLs to parameters in API’s that are now
required, it will fail with an (argument) exception.
Samples usage or steps to
take to migrate code
Removing support for clr-namespace construct in XAML
Brief description:
Support for clr-namespace construct in XAML namespaces is being removed. This construct was designed for
common language runtime-based apps, and is not appropriate for the Windows Runtime.
Languages C#, C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —28
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and
details
If your app tries to use reference using clr-namespace, errors similar to the following will occur
:
Samples
usage or
steps to take
to migrate
code
Before Now change to
xmlns:local=”clr-namespace:breakingchanges”
xmlns:local=”using:
breakingchanges”
xmlns:local=”clr-namespace:
breakingchanges;assembly=MyAssembly”
xmlns:local=”using:
breakingchanges”
xmlns:System=”clr-
namespace:System;assembly=mscorlib”
<System:String>…</System:String>
<x:String>…</x:String>
Windows Store
Windows.ApplicationModel.Store
New method CurrentAppSimulator.ReloadSimulatorAsync
Brief description:
Added ReloadSimulatorAsync API.
We are adding a method to make the offline testing of Windows Store APIs easier for developers. It will allow
the CurrentAppSimulator class state to be reloaded with new simulator settings from an XML file. Our current
runtime already supports loading the file from a specific file in a known location on startup. This API however,
will allow them to load the file directly from any local file path at any time, which will simplify this process
significantly.
Languages JavaScript, C++, .NET
Issue and details New API for testing code ISVs write with Store APIs against various license
states.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —29
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples usage or steps to
take to migrate code
JavaScript sample code:
var currentApp =
Windows.ApplicationModel.Store.CurrentAppSimulator;
var simulatorSettingsFilePath =
Windows.ApplicationModel.Package.current.installedLocat
ion.path + "\\proxy1.xml";
Windows.Storage.StorageFile.getFileFromPathAsync(simula
torSettingsFilePath).then(
function (settingsFile) {
currentApp.reloadSimulatorAsync(settingsFile).done();
});
New and updated method to get signed receipts for purchases
Brief description:
Added GetAppReceiptAsync and GetProductReceiptAsync and added a parameter to
RequestAppPurchaseAsync and RequestProductPurchaseAsync APIs.
These new methods are available as members of CurrentApp and CurrentAppSimulator. They allow an app
which might have a valuable web service, to request a receipt signed by the Store web service to prove to the
app’s web services that the user/app calling has indeed acquired the app or product from the Store. The receipt
can be used as a proof to activate content or features on the ISV web service based on purchases made from
within the app.
To support getting receipts in the most efficient manner for various purchase scenarios, we’ve also added an
addition Boolean includeReceipt parameter to the existing purchase operations so they will be able to return the
receipt directly in the purchase operations as well.
Note that GetProductReceiptAsync will not be implemented for Windows 8. Calling it will return an HRESULT
error code of E_NOTIMPL.
Languages JavaScript, C++, .NET
Issue and details New API for acquiring an app receipt and an additional parameter added to
request purchase APIs.
Samples usage or steps to
take to migrate code
JavaScript sample code for new APIs:
var currentApp =
Windows.ApplicationModel.Store.CurrentAppSimulator;
//var currentApp =
Windows.ApplicationModel.Store.CurrentApp;
currentApp.GetAppReceiptAsync().then(
function (appReceipt) {
// add code here to send the app receipt to your
web service for verification;
});
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —30
May 31, 2012
© 2012 Microsoft. All rights reserved.
JavaScript sample code showing impact of update to purchase APIs:
You’ll need to add a Boolean parameter to the call. The parameter value to
match original API implementation behavior should be to put a value of “false”.
Most developers will not need receipts so this would be set to “false” for most
apps.
var currentApp =
Windows.ApplicationModel.Store.CurrentAppSimulator;
currentApp.RequestAppPurchaseAsync(false).done();
JavaScript sample code using the updated APIs for apps that want to get the
receipt in the purchase transaction:
var currentApp =
Windows.ApplicationModel.Store.CurrentAppSimulator;
//var currentApp =
Windows.ApplicationModel.Store.CurrentApp;
currentApp.RequestAppPurchaseAsync(true).then(
function (appReceipt) {
// add code here to check if the purchase was
successful then send the app receipt to your web
service for verification;
});
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —31
May 31, 2012
© 2012 Microsoft. All rights reserved.
App manifest
Lock screen notifications and certain background tasks are now mutually required
Brief description:
Changes:
At app installation time it is now enforced that if a lock screen notification type is specified in an app manifest,
an appropriate background task must also be specified. In addition, if an appropriate background task is
specified, a lock screen notification type must also be specified. The types of background tasks that require a
lock screen notification (and the types that must be specified when a lock screen notification type is present)
are:
· Control Channel
· Timer
· Push Notification
Why is this change needed?
Without this change, if apps specify either a background task or lock screen capabilities, but not both, their app
will not be able to run in the background or appear on the lock screen. It will not be able to successfully call
the APIs allowing it to request access to these items, nor will it appear as an option in Windows UI. This change
will allow developers to be informed of the problem ahead of time to avoid head-scratching investigations
trying to figure out why their app isn’t behaving as expected.
Who is impacted?
Developers who have Metro style apps that specify only one of lock screen or background capabilities in their
manifest, but not the other, will see their apps fail to install.
Action required:
If you believe that your app will be affected by this change, you must do the following:
If your app only specifies a background task, but not a lock screen notification:
If your app truly needs one of the background rights called out above, you must specify a lock screen notification in your app manifest
If your app does not need one of the background rights called out above, you can remove the background declaration from your app manifest
If your app only specifies a lock screen notification type, but not a background task:
If your app truly needs to be on the lock screen, you must specify a background task type of either Control Channel, Timer, or Push Notification in your app manifest
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —32
May 31, 2012
© 2012 Microsoft. All rights reserved.
o Control Channel should only be used if your app truly needs it since there is a limit of 3 apps that may use this at any given time
If your app does not need to be on the lock screen, you can remove the lock screen declaration from your app manifest
If none of the above steps are performed and your app only specifies one of lock screen or background, but not
the other, it will fail to install.
Samples:
Sample Manifest
<?xml version="1.0" encoding="utf-8"?> <Package xmlns="http://schemas.microsoft.com/appx/2010/manifest"> <!--IDENTITY--> <Identity Name="Microsoft.SDKSamples.LockscreenApps.CS" ProcessorArchitecture="neutral" Publisher="CN=Michael McCormack" Version="1.0.0.0" ResourceId="NorthAmerica"/> <Properties> <Framework>false</Framework> <DisplayName>Basic Mosh App</DisplayName> <Description>Basic Mosh App Prototype</Description> <PublisherDisplayName>Microsoft Corporation</PublisherDisplayName> <Logo>Images\Logo.png</Logo> </Properties> <Resources> <Resource Language="en-us"/> </Resources> <Capabilities> <Capability Name="internetClient" /> </Capabilities> <Applications> <Application Id="LockScreenAppsCS.App012345678901" Executable="BasicMoshApp.exe" EntryPoint="main"> <VisualElements DisplayName="Basic Mosh app" Logo="Images\Logo.png" SmallLogo="Images\SmallLogo.png" Description="Basic Mosh App description" BackgroundColor="#AA00AA" ForegroundText="light" ToastCapable="true"> <DefaultTile WideLogo="Images\WideLogo.png" ShortName="BMA" ShowName="allLogos"/> <LockScreen Notification="badgeAndTileText" BadgeLogo="Images\badge.png"/> <SplashScreen Image="Images\SplashImage.png"/> </VisualElements> <Extensions> <Extension Category="windows.search"/> <Extension Category="windows.shareTarget"> <ShareTarget>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —33
May 31, 2012
© 2012 Microsoft. All rights reserved.
<DataFormat>text</DataFormat> </ShareTarget> </Extension> <Extension Category="windows.backgroundTasks" Executable="BasicMoshApp.exe" EntryPoint="main"> <BackgroundTasks> <Task Type="timer"/> </BackgroundTasks> </Extension> </Extensions> </Application> </Applications> <Prerequisites> <OSMinVersion>6.2</OSMinVersion> <OSMaxVersionTested>6.2</OSMaxVersionTested> </Prerequisites> </Package>
Language Requirement
Apps uploaded to the Store must have at least one or more Store-required language declared in the package
manifest. The Package.storeassociation.xml schema has changed this requirement. This file is generated by
Visual Studio when the project is being associated with the Store or if a package is being built for the Store.
Impact
All existing apps that have previously been associated with the Store or built a package for the Store will receive
the following error:
The Language attribute of the Resource element in the app manifest must have a value that is within
the set of languages supported by the Store. The languages that Store supports are listed at
http://go.microsoft.com/fwlink/p/?LinkId=223184.
The fix is to remove the Package.StoreAssociation.xml file from the project and re-associate with the Store.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —34
May 31, 2012
© 2012 Microsoft. All rights reserved.
App manifest (minor) breaking changes
Brief description:
Languages None (schema changes only)
Issue and details The app manifest format has a couple very minor breaking changes, in
addition to a few additive changes to support new scenarios for our
platform. Build 8296 and later will have the updated manifest schema and
binaries for the Windows 8 Release Preview. Included in this doc is a
summary of all the changes for developers to review to get their apps
ready for the Release Preview.
Samples usage or steps to
take to migrate code
If your manifest contains any of the elements/attributes that are being
changed, then your app packages will fail to install with the error “Invalid
Manifest schema”, until you rebuild the packages with the updated
schema. The AppxManifest.xml manifest file will need to be fixed as per
the changes mentioned below.
Details of all manifest changes
(Additive/Non-breaking) changes
Affected Element/Attribute Change description/
Rationale
Applications/Application/VisualElements
/
DefaultTile/@ShortName
The character limit is increased to 40 chars (from 13
chars) for the attribute “ShortName”. Tiles made a
change to allow up to 2 lines of text for ShortName
on tiles, which means we are able to show more text
than just 13 chars.
Extension
Category="windows.shareTarget"
The schema for ShareTarget extension data type
“ST_DataFormat” now also supports URLs.
We expanded the allowable characters, to enable
developers to include characters that could appear
in a URL: {., /, \, :}. The new schema is as follows:
<xs:simpleType name="ST_DataFormat">
<xs:restriction base="ST_NonEmptyString">
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleType>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —35
May 31, 2012
© 2012 Microsoft. All rights reserved.
Applications/Application/Extensions/Ext
ension/@RuntimeType
InProcessServer/ActivatableClass/@Acti
vatableClassId
OutOfProcessServer/ActivatableClass/@
ActivatableClassId
1. The schema for ACIDs is updated to allow
Unicode characters (was ASCII only) to meet
GB18030 requirement for certification in China.
The new schema for these 3 fields in the
manifest is as follows:
<xs:simpleType name="ST_ActivatableClassId">
<xs:restriction base="ST_FileNameCharSet">
<xs:pattern value="([^.]+)(\.[^.]+)*"/>
<xs:maxLength value="255"/>
</xs:restriction>
</xs:simpleType>
2. Removed semantic validation of disallowed
language keywords for these fields. We were
validating that Windows Runtime activatable
class IDs (aka ACIDs) don’t use identifiers from a
list of known keywords. However, the list of
keywords was not comprehensive across the
four languages Windows Runtime supports.
Furthermore, these languages can change
independently causing us to get in a situation in
the future where we won’t be able to block new
keywords because of app compatibility.
Breaking changes
Affected Element/Attribute Change description/
Rationale
Package/Properties/@Framework Framework package cannot contain the following
elements:
Package/@Capabilities
Package/@Applications
We want to disallow frameworks from declaring
capabilities. Since different versions of frameworks
can co-exists for a user, allowing frameworks to
declare capabilities invalidates several of our design
assumptions for app containers. Additionally, it also
does not make sense for a framework package to
have user-visible tile or implement app specific
contracts. This validation is enforced semantically in
the Manifest API.
Applications/Application/
VisualElements/@InitialRotationPreferen
ce
We are updating the schema to disallow specifying
an empty InitialRotationPreference element. Please
note that specifying InitialRotationPreference is still
optional. The new schema just ensures that if you
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —36
May 31, 2012
© 2012 Microsoft. All rights reserved.
specify InitialRotationPreference, you have at least
one Preference specified. You can't leave it blank.
Old schema New schema
<xs:complexType
name="CT_InitialRotat
ionPreference">
<xs:sequence>
<xs:element
name="Rotation"
minOccurs="0"
maxOccurs="4">
<xs:complexType>
<xs:attribute
name="Preference"
type="ST_RotationPref
erence"
use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
<xs:complexType
name="CT_InitialRota
tionPreference">
<xs:sequence>
<xs:element
name="Rotation"
maxOccurs="4">
<xs:complexType>
<xs:attribute
name="Preference"
type="ST_RotationPre
ference"
use="required"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
Old XML New XML
The below XML was
considered valid with
the old schema:
<InitialRotationPrefer
ence>
</InitialRotationPrefer
ence>
The new schema
enforces there is at
least one rotation
element defined:
<InitialRotationPrefer
ence>
<Rotation
Preference="portrait"
/>
</InitialRotationPrefe
rence>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —37
May 31, 2012
© 2012 Microsoft. All rights reserved.
HTML5/CSS/JavaScript
requestAnimationFrame API
The requestAnimationFrame API, or msRequestAnimationFrame as it is currently implemented, is being
updated to match changes proposed in the W3C Web Performance requestAnimation and High
Resolution Time specifications. Though this API is only available in prefixed format, it is widely used for
script based animations within WWAs and websites. As such, please evaluate how this breaking change
may impact your collateral.
Summary
# Change Old IDL New IDL
1 Changing the time base of
the
msRequestAnimationFrame
callback parameter
callback FrameRequestCallback
= void (DOMTimeStamp time); callback
FrameRequestCallback =
void
(DOMHighResTimeStamp
time);
2 Removing
msAnimationStartTime
attribute in favor of
performance.msNow()
function
partial interface Window {
unsigned long long
msAnimationStartTime;
};
partial interface
Performance {
DOMHighResTimeStamp
msNow();
};
3 msCancelRequestAnimationFr
ame
renamed to
msCancelAnimationFrame
partial interface Window {
void
msCancelRequestAnimationFrame(
long handle);
};
partial interface
Window {
void
msCancelAnimationFrame(
long handle);
};
Change Description
The detailed description for each change is given below:
#1 Changing the time base of the msRequestAnimationFrame callback parameter
Previously, the time parameter of the msRequestAnimationFrame callback was defined to be a
DOMTimeStamp. For most other purposes, this definition of time is sufficient as that value represents
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —38
May 31, 2012
© 2012 Microsoft. All rights reserved.
time to millisecond precision for any instant that is within approximately 285,616 years from 01
January, 1970 UTC.
In practice, DOMTimeStamp time values are subject to both clock skew and adjustment of the system
clock. The value of time may not always be monotonically increasing and subsequent values may
decrease. Further, the resolution provided by DOMTimeStamp may not be sufficient for tasks related
to animation script.
A high resolution, monotonically increasing time value is desired in the following cases,
When calculating the animation state from script, developers will need to accurately know the
amount of time that has elapsed in the animation in order to properly update the next scene of
the animation.
In order to cue audio to a specific point in an animation or ensure that the audio is synchronized
with the animation, developers will need to accurately know the amount of time elapsed in the
animation and audio.
When calculating the instant frame rate of a script based animation, developers will need sub-
millisecond resolution in order to determine if an animation is drawing at 60 FPS. Without sub-
millisecond resolution, a developer can only determine if an animation is drawing at 58.8 FPS or
62.5 FPS.
This change will update the interface as follows:
Before the change
partial interface Window {
long msRequestAnimationFrame(FrameRequestCallback callback);
};
callback FrameRequestCallback = void (DOMTimeStamp time);
After the change
partial interface Window {
long msRequestAnimationFrame(FrameRequestCallback callback);
};
callback FrameRequestCallback = void (DOMHighResTimeStamp time);
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —39
May 31, 2012
© 2012 Microsoft. All rights reserved.
The DOMHighResTimeStamp represents time values in sub-millisecond resolution, as measured from
the beginning of the navigation of the document, and not subject to system clock skew or
adjustments (monotonically increasing).
#2 Removing window.msAnimationStartTime attribute in favor of window.performance.msNow()
function
As a part of the change to move to a high resolution, monotonically increasing time value measured
from the beginning of the navigation of the document, we needed to provide an API that gives the
current time in that time base: window.performance.msNow() is that function. As
window.msAnimationStartTime used the old time base, we will be removing the
window.msAnimationStartTime attribute in favor of window.performance.msNow() function. The
window.performance.msNow() API surface will resemble the Date.now() API more closely.
Before the change
Whereas before the change, you would have written code as so:
var start = window.msAnimationStartTime;
function step(timestamp)
{
var progress = timestamp - start;
d.style.left = Math.min(progress/10, 200) + "px";
if (progress < 2000)
{
msRequestAnimationFrame(step);
}
}
msRequestAnimationFrame(step);
After the change
Now, you will write code as so:
var start = window.performance.msNow();
function step(timestamp)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —40
May 31, 2012
© 2012 Microsoft. All rights reserved.
{
var progress = timestamp - start;
d.style.left = Math.min(progress/10, 200) + "px";
if (progress < 2000)
{
msRequestAnimationFrame(step);
}
}
msRequestAnimationFrame(step);
#3 Renaming msCancelRequestAnimationFrame to msCancelAnimationFrame
We are renaming the msCancelRequestAnimationFrame function to msCancelAnimationFrame in
order to be interoperable with other vendor implementations and the specification:
Before the change
msCancelRequestAnimationFrame(handle);
After the change
msCancelAnimationFrame(handle);
Action to Take
If your app or code you own relies on animating using the msRequestAnimationFrame API, you will want
to evaluate the new behavior and adjust your code to restore the expected behavior.
IndexedDB numeric constants have been removed
In order to be w3c spec compliant the numeric constants have been removed and replaced with string values:
Affected properties on the current spec and their string values:
Interface Previous New Value
IDBRequest
unsigned short readyState DOMString readyState;
const unsigned short LOADING = 1; “pending”
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —41
May 31, 2012
© 2012 Microsoft. All rights reserved.
const unsigned short DONE = 2; “done”
IDBCursor
unsigned short direction; DOMString direction;
const unsigned short NEXT = 0; >>> “next” “next”
• const unsigned short NEXT_NO_DUPLICATE = 1 "nextunique"
• const unsigned short PREV = 2 “prev”
• const unsigned short PREV_NO_DUPLICATE = 3 “prevunique”
IDBTransaction
unsigned short mode DOMString mode;
const unsigned short READ_ONLY = 0 “readonly”
const unsigned short READ_WRITE = 1 “readwrite”
const unsigned short VERSION_CHANGE = 2 “versionchange”
The following methods are impacted by these changes:
• IDBDatabase.transaction(any storeNames, optional DOMString mode);
• IDBObjectStore.openCursor(optional any? range, optional DOMString direction);
• IDBIndex.openCursor(optional any? range, optional DOMString direction);
• IDBIndex.openKeyCursor (optional any? range, optional DOMString direction);
Fixing your code
The largest impact is when using the IDBDatabase.transaction method. This table provides examples of
changes to make to your code:
Consumer Preview Release Preview
db.transaction(“objectStore0”, IDBTransaction.READ_WRITE);
db.transaction(“objectStore0”, IDBTransaction.READ_ONLY);
db.transaction(“objectStore0”, “readwrite”);
db.transaction(“objectStore0”, “readonly”);
CSS Flexbox: moving to latest W3C syntax
The CSS Flexbox syntax was modified to move to the latest W3C specification. The new syntax is functionally
equivalent to the old syntax, and the table below describes the changes and substitutions to make to existing
CSS properties. In some cases (e.g. “-ms-box” -> “-ms-flexbox”) a simple find-and-replace is all that is needed,
while in others (e.g. “-ms-box-flex” -> “-ms-flex”) different properties values and combinations of properties
may be needed to achieve the same affect.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —42
May 31, 2012
© 2012 Microsoft. All rights reserved.
Property Value New Property New Value Update strategy
display -ms-box display -ms-flexbox Find and replace
display -ms-inline-box display -ms-inline-flexbox Find and replace
-ms-box-align before -ms-flex-align start Find and replace
-ms-box-align after -ms-flex-align end Find and replace
-ms-box-align middle -ms-flex-align center Find and replace
-ms-box-align stretch -ms-flex-align stretch Find and replace
-ms-box-align baseline -ms-flex-align baseline Find and replace
-ms-box-pack start -ms-flex-pack start Find and replace
-ms-box-pack end -ms-flex-pack end Find and replace
-ms-box-pack center -ms-flex-pack center Find and replace
-ms-box-pack justify -ms-flex-pack justify Find and replace
-ms-box-direction normal -ms-flex-direction row or column combines -ms-
box-direction, -
ms-box-orient
-ms-box-direction reverse -ms-flex-direction row-reverse or
column-reverse
combines -ms-
box-direction, -
ms-box-orient
-ms-box-orient horizontal -ms-flex-direction row or row-reverse combines -ms-
box-direction, -
ms-box-orient
-ms-box-orient vertical -ms-flex-direction colum or column-
reverse
combines -ms-
box-direction, -
ms-box-orient
-ms-box-orient inline-axis -ms-flex-direction row or row-reverse combines -ms-
box-direction, -
ms-box-orient
-ms-box-orient block-axis -ms-flex-direction colum or column-
reverse
combines -ms-
box-direction, -
ms-box-orient
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —43
May 31, 2012
© 2012 Microsoft. All rights reserved.
Property Value New Property New Value Update strategy
-ms-box-lines single -ms-flex-wrap none combines -ms-
box-lines and -
ms-box-line-
progression
-ms-box-lines multiple -ms-flex-wrap wrap or wrap-
reverse
combines -ms-
box-lines and -
ms-box-line-
progression
-ms-box-line-
progression
normal -ms-flex-wrap wrap combines -ms-
box-lines and -
ms-box-line-
progression
-ms-box-line-
progression
reverse -ms-flex-wrap wrap-reverse combines -ms-
box-lines and -
ms-box-line-
progression
-ms-box-ordinal-group <value> -ms-flex-order <value> New default value
is 0, old default
value was 1. Code
that assumes the
old default of 1
and doesn’t
initialize it to a
specific value will
need to update to
take this new
default into
account.
-ms-box-flex <value>
Sample:
#foo {
width: 100px;
-ms-box-flex: 1;
-ms-flex <value, auto>
Sample:
#foo {
width: 100px;
-ms-flex: 1
The new syntax
allows developers
to specify positive
or negative flex.
Default positive
flex is 1, default
negative flex is 0.
The preferred size
is now specified
as a value
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —44
May 31, 2012
© 2012 Microsoft. All rights reserved.
Property Value New Property New Value Update strategy
} auto;
}
Or
#foo {
-ms-flex: 1
100px;
}
provided to -ms-
flex rather than
through the
“width” property.
In general, most
uses of the old
syntax will simply
find and replace
the old property
for the new
property and
append “auto” as
a second value.
Un-prefixed versions of web performance, CSS transitions, and CSS animations, and font
features settings APIs now available
Description:
The following Internet Explorer platform features are now available without a Microsoft prefix. These newly-
added, un-prefixed APIs are "aliases" of the prefixed versions--they redirect to the same implementation (no
behavior change). The additional un-prefixed name is shown in parentheses:
Aliased JavaScript APIs:
- Media Queries
msMatchMedia (matchMedia)
- Indexed Database
msIndexedDB (indexedDB)
- Page Visibility
msVisibilityState (visibilityState)
msHidden (hidden)
- Animation Timing
msRequestAnimationFrame (requestAnimationFrame)
msCancelRequestAnimationFrame (cancelAnimationFrame)
msAnimationStartTime (animationStartTime)
- Efficient Script Yielding
msSetImmediate (setImmediate)
msClearImmediate (clearImmediate)
- CSS Transforms
msTransform (transform) msTransformOrigin (transformOrigin)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —45
May 31, 2012
© 2012 Microsoft. All rights reserved.
msPerspective (perspective) msPerspectiveOrigin (perspectiveOrigin) msTransformStyle (transformStyle) msBackfaceVisibility (backfaceVisibility)
- CSS Transitions
msTransition (transition) msTransitionDelay (transitionDelay) msTransitionDuration (transitionDuration) msTransitionProperty (transitionProperty) msTransitionTimingFunction (transitionTimingFunction) - CSS Animations
msAnimation (animation) msAnimationDelay (animationDelay) msAnimationDirection (animationDirection) msAnimationDuration (animationDuration) msAnimationFillMode (animationFillMode) msAnimaionIterationCount (animaionIterationCount) msAnimationName (animationName) msAnimationPlayState (animationPlayState) msAnimationTimingFunction (animationTimingFunction) - CSS Font Properties
msFontFeatureSettings (fontFeatureSettings)
Aliased CSS Properties:
- CSS Transforms
-ms-transform (transform) -ms-transform-origin (transform-origin) -ms-perspective (perspective) -ms-perspective-origin (perspective-origin) -ms-transform-style (transform-style) -ms-backface-visibility (backface-visibility)
- CSS Transitions
-ms-transition (transition) -ms-transition-delay (transition-delay) -ms-transition-duration (transition-duration) -ms-transition-property (transition-property) -ms-transition-timing-function (transition-timing-function) - CSS Animations
-ms-animation (animation) -ms-animation-delay (animation-delay) -ms-animation-direction (animation-direction) -ms-animation-duration (animation-duration) -ms-animation-fill-mode (animation-fill-mode) -ms-animation-iteration-count (animation-iteration-count) -ms-animation-name (animation-name) -ms-animation-play-state (animation-play-state) -ms-animation-timing-function (animation-timing-function) - CSS Font Properties
-ms-font-feature-settings (font-feature-settings)
- CSS Keyframes
@-ms-keyframes (@keyframes)
Aliased Events:
- Page Visibility
"msvisibilitychange" ("visibilitychange")
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —46
May 31, 2012
© 2012 Microsoft. All rights reserved.
- CSS Transitions
"MSTransitionStart" ("transitionstart")
"MSTransitionEnd" ("transitionend")
- CSS Animations
"MSAnimationStart" ("animationstart")
"MSAnimationEnd" ("animationend")
"MSAnimationIteration" ("animationiteration")
Important: Due to the duality of supporting both a prefixed and un-prefixed version of the above APIs, this is a
breaking change for the following:
Note: Existing apps and frameworks (e.g., Windows Library for JavaScript and jQuery) have already been
statically analyzed and do not appear to rely on any of the following breaking changes.
1. Event.type -- where the event is: "MSTransitionStart", "MSTransitionEnd", "MSAnimationStart",
"MSAnimationEnd", "MSAnimationIteration"
2. CSSRule.type – where the reported value is 8 or 9
3. document.createEvent -- where the parameter is "MSTransitionEvent", "MSAnimationEvent"
4. initMSTransitionEvent/initMSAnimationEvent
5. MSTransitionEvent, MSAnimationEvent, MSMediaQueryList, MSCSSKeyframesRule,
MSCSSKeyframeRule, MSKEYFRAMES_RULE, MSKEYFRAME_RULE
Note: The following may but probably won't be problematic. If you believe your app could be impacted,
please use the attached run-time code checker which will report any of the previously noted and following
potential issues.
cssText (reading-only, "+=" usage is OK), TransitionEvent.propertyName, style.msTransitionProperty
(reading-only, "+=" usage is OK), getAttribute("style") – where the string returned contains one of
the above-mentioned Aliased CSS Properties.
Further details
The breaking changes just listed are described below in more detail:
1- event.type
The event.type will always report a string that corresponds to the un-prefixed version of the dispatched
event. Thus, if a "MSTransitionEnd" event was registered via addEventListener, the dispatched event's "type"
property will report "transitionend". Previously it reported "MSTransitionEnd".
Affected usage pattern: if (event.type == "MSTransitionStart") {
// This code will now be skipped
}
2- createEvent("MSTransitionEvent") or createEvent("MSAnimationEvent")
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —47
May 31, 2012
© 2012 Microsoft. All rights reserved.
The createEvent API will no longer work with the legacy prefixed interfaces. Instead, code that
programmatically creates transition or animation event objects will need to use the un-prefixed form:
createEvent("TransitionEvent") or createEvent("AnimationEvent") respectively.
Affected usage pattern: var te = document.createEvent("MSTransitionEvent");
3- initMSTransitionEvent(...) or initMSAnimationEvent(...)
These event initializer methods (for transition and animation event objects) will no longer be available after
this change. Code that needs to initialize transition or animation event objects will need to use the un-
prefixed form: initTransitionEvent(...) or initAnimationEvent(...)
Affected usage pattern: // building on the above affected usage pattern...
te.initMSTransitionEvent("MSTransitionStart", false, false, ...);
4- Style serialization via cssText or getAttribute("style")
Style serialization (creating a string representation of a set of CSS style rules) will no longer emit the
prefixed form of the CSS Properties affected by this change. Rather, the style serializer will emit the un-
prefixed form. For example, previously setAttribute("style", "-ms-transition:...") would be retrieved via
getAttribute("style") as the string "-ms-transition:...", but after the change would be returned as
"transition:...".
Affected usage pattern: if (element.getAttribute("style").indexOf("-ms-transform") != -1)
...
if (element.style.cssText.indexOf("-ms-transform") != -1)
...
5- Interface renames
The following interface names (exposed to JavaScript) are being renamed. Usage of the old name will no
longer work after this change. Affected code should be updated to use the new name instead:
MSMediaQueryList -> MediaQueryList
MSTransitionEvent -> TransitionEvent
MSAnimationEvent -> AnimationEvent
MSCSSKeyframeRule -> CSSKeyframeRule
MSCSSKeyframesRule -> CSSKeyframesRule
Affected usage pattern: // Adding new prototype props...
MSTransitionEvent.prototype.myTransitionProperty = function() { ... }
// Patching existing props...
Object.defineProperty(MSTransitionEvent.prototype, "propertyName", {
get: function() {..}, set: function() {..}});
6- Keyframe(s) constants renamed
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —48
May 31, 2012
© 2012 Microsoft. All rights reserved.
The following keyframe constant values are being renamed and their numbers are changing to match the
standard. Code relying on the old name or number will no longer work after this change. Affected code
should be updated to use the new names (and numbers) instead:
CSSRule.MSKEYFRAMES_RULE (8) -> CSSRule.KEYFRAMES_RULE (7)
CSSRule.MSKEYFRAME_RULE (9) -> CSSRule.KEYFRAME_RULE (8)
Affected usage patterns:
CSSRule.MSKEYFRAME[S]_RULE references.
7- CSSRule.type value updated for keyframe(s) rules
The value of the CSSRule object's "type" property is being adjusted when the actual rule instance is a
keyframes or keyframe rule. Previously the type property returned 8 for a keyframes rule and 9 for a
keyframe rule. After this change, the type property will return 7 for a keyframes rule and 8 for a keyframe
rule.
Affected usage patterns: var sheetRules = document.styleSheets[0].cssRules;
for (var i=0; i < sheetRules.length; i++) {
if (sheetRules[i].type == 8) {
// Hard-coded literal value, rather than CSSRule.MSKEYFRAME[S]_RULE
ref.
}
}
Note: this change also updates the developer tools for Internet Explorer (and Visual Studio) for inspecting CSS
styles and tracing CSS Styles. These tools are updated with this change to display the un-prefixed form of any
of the above aliased CSS properties (whether specified with or without a prefix).
HTML Views: Scrollboundaries act as a limit on scrollLeft/scrollTop
Since //BUILD, we have been communicating both externally and to internal partners that the –ms-scroll-limit-*
properties act to constrain the possible values of scrollLeft/scrollTop. This change is to fix bring the
implementation in-line with that definition. After this change the following equations dictate valid values for
scrollLeft/scrollTop:
-ms-scroll-limit-x-min <= scrollLeft <= -ms-scroll-limit-x-max
-ms-scroll-limit-y-min <= scrollTop <= -ms-scroll-limit-y-max
Prior to this change, the following equations dictated the behavior:
-ms-scroll-limit-x-min <= scrollLeft <= -ms-scroll-limit-x-max – viewPortSize
-ms-scroll-limit-y-min <= scrollTop <= -ms-scroll-limit-y-max - viewPortSize
Update to getClientRects, getBoundingClientRects, and offsetLeft, offsetTop, width, and
height
We have updated a related set of issues that currently result in several APIs resolving dimensions incorrectly.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —49
May 31, 2012
© 2012 Microsoft. All rights reserved.
1. Updated dimensions in CSS3 Regions to be computed in document space, rather than relative to the
fragment in which an element appears.
2. Fixed getClientRects to correctly resolve against the layout viewport rather than the visual viewport
established in certain zoomed scenarios.
3. Fixed getClientOrigin, getElementRects, and getBoundingClientRect to not offset a containing
display:none iframe’s position (which currently results in negative values since these APIs all return 0
when an element is display: none).
4. Fixed getClientRects, getBoundingClientRect, offsetTop, offsetLeft, width, and height to correctly return
results that are relative to their containing document when they are in a frame. Currently they are
affected by any (e.g.) transforms on the containing iframe or an ancestor of the containing iframe.
Updating backface-visibility to latest CSS3 spec
The "backface visibility" property determines whether or not the "back" side of a transformed element is visible
when facing the viewer. With an identity transform, the front side of an element faces the viewer. Applying a
rotation about Y of 180 degrees (for instance) would cause the back side of the element to face the viewer.
Earlier the backface-visibility was calculated as follows:
1. Compute a matrix representing the accumulated transform from the viewport, taking the translations
due to the CSS visual formatting mode, the perpsective and transformation matrices into account, in a
similar manner to the computation of the accumulated transform for an element in a 3D rendering
context.
2. If the component of the matrix in row 3, column 3 is negative, then the element should be hidden,
otherwise it is visible
This has been updated to match the latest spec as follows:
1. For an element in a 3D rendering context, compute its accumulated 3D transformation matrix. For an
element not in a 3D rendering context, compute its transformation matrix.
2. If the component of the matrix in row 3, column 3 is negative, then the element should be hidden.
Otherwise it is visible.
COM interfaces for SVG Filters have been removed
This change will affect anyone using COM interfaces for SVG Filters. This will not impact authors of Metro style
apps using JavaScript and HTML.
The COM interfaces for all SVG Filters have been removed. This includes the removal of:
· ISVGFilterElement
· ISVGBlendElement
· ISVGFEColorMatrixElement
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —50
May 31, 2012
© 2012 Microsoft. All rights reserved.
· ISVGComponentTransferFunctionElement
· ISVGFECompositeElement
· ISVGFEDiffuseLightingElement
· ISVGFEDistantLightElement
· ISVGFEPointLightElement
· ISVGFESpotLightElement
· ISVGFEDisplacementMapElement
· ISVGFEGaussianBlurElement
· ISVGFEImageElement
· ISVGFEMorphologyElement
· ISVGFEOffsetElement
· ISVGFESpecularLightingElement
· ISVGFETurbulenceElement
Use JavaScript with the IDispatch interface instead. It also has performance benefits over the COM version.
COM interfaces for other SVG content are still available.
We don’t anticipate many users being affected as some of the SVG Filters COM interfaces for haven't been
working correctly since 2/29 without noticeable breakages.
SafeHTML validation for inline event handlers on unattached elements
What’s changing
For Windows Metro style apps using JavaScript,, local context functions that can accidentally include script and
markup are validated with the SafeHTML library. In particular, innerHTML, outerHTML, insertAdjacentHTML,
document.write(), document.writeln(), DOMParser, and pasteHTML are all validated to prevent accidental
insertion of unsafe content. These functions will throw an exception if they are used to inject unsafe content
within the local context. The exception for unsafe content inserted into unattached elements is deferred, and
only thrown if the unattached element is attached to the DOM. For example, the following code will not throw
an exception, as long as the <div> is not attached to the DOM.
var d = document.createElement("div");
d.innerHTML = "<script src='foo.js'/>";
Unfortunately, script included in some inline event handlers is able to execute, even if the element is not
attached to the DOM. To mitigate this security issue, we will throw an exception immediately if an inline
event handler is dynamically added to an unattached element, such as the onload and onerror event
handlers.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —51
May 31, 2012
© 2012 Microsoft. All rights reserved.
Who is Affected, and What to Do
If you have any code that sets inline event handlers on unattached elements with the functions listed above,
you will be affected by this change. For example, the following code will be affected due to the onerror event
handler -
var d = document.createElement("div");
d.innerHTML = "<img src='' onerror='foo()'>";
In most instances, the content should be sanitized with window.toStaticHTML().
For more information about SafeHTML validation and secure practices for Metro style apps using JavaScript,,
please see http://msdn.microsoft.com/en-us/library/windows/apps/hh849625.aspx
Change to CSS3 property transform-origin
This scoped change to make us compliant with CSS3. This change will *not* impact developers who have
correctly set the value of transform-origin. This change will only impact if the value of transform-origin was set
incorrectly.
Transform-origin supports the following values:
[ <percentage> | <length> | left | center | right | top | bottom]
OR
[
[ <percentage> | <length> | left | center | right ]
&&
[ <percentage> | <length> | top | center | bottom ]
] <length>?
With this change if any input value for transform-origin is incorrect, we will ignore the entire string.
Example:
Input: transform-origin: left center 0%
Before this change: Transform-origin would be set to “left center”
After the change: Transform-origin would be set to “ “ or null.
Input: transform-origin: left center ABC
Before this change: Transform-origin would be set to “left center”
After the change: Transform-origin would be set to “ “ or null.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —52
May 31, 2012
© 2012 Microsoft. All rights reserved.
CSS animations and transitions with display:none no longer runs
This may be a breaking change for display:none on elements with (or on elements that have children with) CSS
Animations and Transitions. For interoperability, general utility, and performance reasons, elements that are not
rendered do not run CSS Animations and CSS Transitions.
With this change, elements with display:none or with an ancestor with display:none do not run CSS animations
and transitions. The change affects unrendered elements, in contrast to visibility:hidden elements which are
rendered but not visible. visibility:hidden elements will continue to run transitions and animations.
When an element’s or an ancestor element’s display property value changes to none, any currently running
animations and transitions immediately stop. The animating properties behave as if the –ms-animation-* and –
ms-transition-* properties were removed. When an element’s or ancestor element’s display property value
changes from none, any applied animations and transitions begin as if the –ms-animation-* and –ms-transition-
* properties had just been applied. CSS Animations will restart from the beginning. CSS Transitions will not
occur until after the display property change has been computed.
Most users will not experience broken content. For those who do, a workaround is to use visibility:hidden
instead of display:none to ensure your animations/transitions continue to run even when content is not visible
to the user. Content containing CSS Transitions with the following coding pattern may also experience broken
behavior:
elem.style.display = "visible"; // display value was previously "none"
elem.style.transitioningProperty = newValue; // transitioningProperty was previously defined as a transitioning
property for the element
Previously, a transition would occur. With the change, a transition will not occur on the transitioning property
because the value change is synchronous with the display property value change. Workaround:
elem.style.display = "visible";
window.getComputedStyle(elem).display // forces format computation of the display property
elem.style.transitioningProperty = newValue;
HTML Views: msSetPointerCapture no longer triggers manipulations
The behaviors around triggering a pan or a zoom on an element via msSetPointerCapture had several
unintended side-effects that motivated removing support.
1. Manipulations triggered in this fashion do not follow parent promotion or chaining semantics resulting
in unintended side effects. In fact, arbitrary chains of elements that can pan or zoom can be
constructed.
2. Building scenarios that rely on the approach of preventing a manipulation and then triggering it via a
procedural call incurs a performance impact that prevents delivery of a polished experience on low-end
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —53
May 31, 2012
© 2012 Microsoft. All rights reserved.
hardware. The feature itself pushes consuming developers towards an approach that will not scale to
low-end hardware.
3. A change in delegate gesture recognition expanded on the existing –ms-touch-action (which from a
manipulation standpoint previously only allowed suppressing all) to allow developers to be more
specific about what behaviors they want to suppress, reducing the need to trigger manipulations after
the fact.
As just mentioned, -ms-touch-action was extended with the following additional properties:
pan-x – finger swipes that are along the horizontal axis result in panning.
pan-y – finger swipes that are along the vertical axis result in panning.
pinch-zoom – converging/diverging more than one finger results in optical zoom.
manipulation – shorthand for specifying the three preceding properties.
Omitting any of these properties results in the pointer messages being delivered to the UI thread and therefore
JavaScript event handlers. For example, to specify something like a ListView item where a user should be able to
pan horizontally, optically zoom on the list, but wants to receive messages to implement vertical cross-slide, the
developer would specify –ms-touch-action:pan-x pinch-zoom.
HTML Touch Views: Changing coordinate space for RTL boundaries/snap-points and
renaming -ms-scroll-boundary-* APIs
Breaking change is to fix three issues:
· Current implementation of boundaries/snap-points introduces an additional coordinate system for
developers to worry about.
· 3rd
party developers are forced to recalculate boundaries/snap-points whenever content is
added/removed, since the origin of the coordinate system changes with the content.
· The naming schema of the properties implies a different coordinate system that does not align with the
implementation.
Renaming -ms-scroll-boundary-* APIs
To address the third bullet, the –ms-scroll-boundary APIs are being renamed to use min/max to make it explicit
that logical values are being used. The naming convention that follows aligns with the coordinate space that
will be introduces in the next section:
-ms-scroll-boundary-left -> -ms-scroll-limit-x-min
-ms-scroll-boundary-right -> -ms-scroll-limit-x-max
-ms-scroll-boundary-top -> -ms-scroll-limit-y-min
-ms-scroll-boundary-bottom -> -ms-scroll-limit-y-max
-ms-scroll-boundary -> -ms-scroll-limit
-ms-content-zoom-boundary-min -> -ms-content-zoom-limit-min
-ms-content-zoom-boundary-max -> -ms-content-zoom-limit-max
-ms-content-zoom-boundary -> -ms-content-zoom-limit
· order for specifying –ms-scroll-limit is as follows: ms-scroll-limit-x-min -ms- scroll-limit-y-min -ms-
scroll-limit-x-max -ms-scroll-limit-y-max
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —54
May 31, 2012
© 2012 Microsoft. All rights reserved.
· order for specifying -ms-content-zoom-limit is as follows: -ms-content-zoom-limit-min -ms-content-
zoom-limit-max in that order.
Changing coordinate space for RTL boundaries/snap-points
The first two bullet points are fixed by changing both the origin and direction of the coordinate space for RTL.
In order to illustrate the change, the following diagrams show how the boundaries work horizontally and how
the compare to scrollLeft. Note, the change in coordinate space is specific to RTL; LTR code should work by
simply updating strings to the new values listed above.
UTF-8 encoding with byte-order mark required for Windows Store onboarding
Brief description:
UTF-8 encoding with a byte-order mark (BOM) is now required for all files in Metro style apps using JavaScript
and HTML and that have a .js, .html, .htm, or .css extension. This is enforced through the Windows App
Certification Kit and the onboarding certification process. The purpose of this change is to ensure all Metro
style apps using JavaScript and HTML that are onboarded to the store are able to take advantage of the
performance benefits of bytecode caching feature for JavaScript files. HTML files previously necessitated this at
runtime, so this requirement merely moves enforcement of the requirement to onboarding time. CSS files
follow this same rule for consistency among the most common file types for HTML5-based Metro style apps.
This requirement applies only to files with these specific extensions. Failures to meet this criteria show up in the
event log at deployment time and in the report from the Windows App Certification Kit.
Languages JavaScript
Issue and
details
JavaScript, HTML, and CSS files must be UTF-8 encoded with a byte-order mark (BOM).
Without this, they fail Windows App Certification and cannot be onboarded to the
Windows Store.
Windows 8 enables a feature called bytecode caching when an app is deployed on the
system, which can garner as much as a 20% performance improvement when running
the JavaScript in your Metro style app using JavaScript and HTML5. During the first
deployment of your app, JavaScript bytecode is pre-generated and cached on behalf
of your app. This only happens when you are not running through Visual studio F5
deployment, however. This bytecode is automatically consumed by the JavaScript
engine whenever the engine requests a JavaScript file. This saves the JavaScript engine
from having to take the time to generate the bytecode each time it is asked to process
that .js file and significantly improves startup and ongoing execution times. Samples
usage or
steps to take
to migrate
code
When you see a File Encoding failure in the Windows App Certification Kit report, you
must perform the following steps to fix each failing file.
Open the file in Visual Studio
Select File | Save <filename> As… from the menu
Click the drop-down next to the Save button and select Save with Encoding…
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —55
May 31, 2012
© 2012 Microsoft. All rights reserved.
Confirm you’d like to replace the file
In the Encoding drop-down, select Unicode (UTF-8 with signature) –
Codepage 65001
Select OK
Note that files newly created in Visual Studio will not see this problem; you will
typically only see this problem when creating files outside of Visual Studio or copying
in scripts from the web, etc.
Default context menus have been removed from HTML media elements
Brief description:
The default context menus for the HTML <audio> and <video> tags have been removed for Metro style apps.
Languages JavaScript
Issue and details In the Consumer Preview by default every <video> and <audio> element in a
Metro style app using JavaScript had a context menu that contained play/pause
and mute/unmute commands. This allowed end-users access basic controls on
media elements even when the developer had not provided their own controls or
used the ‘controls’ attribute on the audio/video tag.
For the Windows 8 Release Preview the default context menus on <video> and
<audio> elements have been removed. Developers should specify the default
controls using the ‘controls’ attribute or provide their own custom controls using
the AppBar. By removing the default context menus on media elements we
ensure that developers take the time to give their users the best control
experience in media and that end-users get a consistent experience across Metro
style apps using JavaScript, Metro style app using C#, C++, or Visual Basic®
, and
XAML, and browsers implemented as Metro style apps.
Samples usage or
steps to take to
migrate code
Apps must provide their own controls for media elements. This can be done by
specifying the controls attribute on the <audio> or <video> tag. A developer
can also create their own custom controls using the AppBar.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —56
May 31, 2012
© 2012 Microsoft. All rights reserved.
Remove default error page for top-level document navigation errors in Metro style apps
using JavaScript and HTML
Brief description:
When navigation errors occur in the top-level document, the WWAHost currently shows a default error page (if
the app did not provide a custom error page). However, a change was made in M3 that restricts top-level
document navigations to packaged content only. Therefore, error cases for the top-level document only occur
when then developer did not configure the package properly. A Top-level document navigation error is
comparable to the crash of the app. In order to be consistent with rest of Windows behavior, WWAHost will
now terminate the app instead of showing the default error page.
Languages JavaScript only
Issue and details Navigation error in
Top-level document
Navigation error in
Iframe
Default Terminate the app* Display about:blank
With Custom error
page
Terminate the app* Display custom error
page
As shown in table above, we now have the following logic:
For top-level document navigation errors, terminate the app and send a
WER report and ETW event (if we are not in debug/development mode)
For iframe navigation errors:
o If the package includes a custom error page (msapp-error.html),
navigates to it
o Otherwise, navigates to about:blank and sends a WER report
Developers will now get WER reports details in the Dev Center for top-level
document navigation errors, or for iframe navigation errors when a custom error
page is not provided.
* Resulting behavior due to design change.
Samples usage or
steps to take to
migrate code
N/A
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —57
May 31, 2012
© 2012 Microsoft. All rights reserved.
Improved error handling
A new flag has been introduced to opt into in order to improve your Windows Library for JavaScript (WinJS)
code.
To enable the new behavior, you call:
WinJS.strictProcessing();
Now, any function resolved for data-win-control or as a right-hand-side in data-win-options, or used as a
binding initializer in data-win-bind, will require a property on the function definition
Consumer Preview Release Preview
// this can’t be used from markup now
function myCoolFunction() {
}
// this can be used from markup now
function myOtherFunction() {
}
myOtherFunction.supportedForProcessing = true;
WinJS.UI.optionsParser no longer defaults to using "global" context
What's Changing
The options and binding parser APIs will be changed to require an explicit "lookup context" parameter, and
lookup of names will only be resolved in the lookup context. Previously, if no such context was provided, or if it
was provided but the name wasn't present in the context, the parser would then automatically go to window
and look the object up there. That fallback behavior will be removed.
There will be no changes to the behavior of the data-win-* attributes.
Who is Affected
Code that is calling the options or binding parser APIs directly. Callers who did not pass a lookup context
previously relied on the fallback to window; they will now have to explicitly pass window as the context.
Before change:
var options = WInJS.UI.optionsParser("{onclick: clickMe}");
After change:
var options = WinJS.UI.optionsParser("{onclick: clickMe}", window);
The amount of non-test code calling the options parser is expected to be extremely small. Most users interact
with these parsers via data-win-* attributes in HTML and a WinJS.*.processAll call (UI, Binding, Resources). These
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —58
May 31, 2012
© 2012 Microsoft. All rights reserved.
calls will be updated so that when they call the parsers they will behave exactly the same way they did before
this change.
To reinforce: data-win-* attributes will continue to work exactly the way they did before.
Removal of reveal and hide PVL animations from Windows Library for JavaScript (WinJS)
WinJS.UI.Animation.reveal
WinJS.UI.Animation.hide
These animations were meant for opening and closing drop-down controls, but were unused by the select
control for Metro style apps using JavaScript and HTML, and were out of date with expected design. As they are
not needed, we removed them from the Windows Library for JavaScript.
WinJS.Fragment.render and WinJS.UI.Pages.get only support “same context” access
WinJS.Fragment.render and WinJS.UI.Pages.get only support “same context” access
Previously Fragment.render and by transitive property Pages.get supported loading content from any network
resource for which your app had access. This meant that a local context piece of code could dynamically load
code from the web, provided it had internet capability (which is request by default in the VS templates).
With this change Fragment.render and Pages.get will only support package content (ms-appx://) requests in the
local context. When running in the web compartment the old behavior is still honored.
If you have an app that is blocked by this, you will need to partition your dynamic fragment or page loading
into a web context IFRAME.
Tweak to JavaScript camel-casing rules
Brief description:
Camel-casing rules for JavaScript view of Windows Runtime APIs changed for member names starting with
three uppercase letters followed by a lowercase letter.
Languages JavaScript
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —59
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue The JavaScript camel-casing rules previously conflicted with Windows Runtime API
Naming guidelines in their treatment of legal names with 2 letter acronym prefixes,
such as IPInformation. While Windows Runtime required this to be IPInformation
instead of IpInformation, JavaScript camel casing made the former ipinformation
(unexpected) and the later ipInformation (expected).
In the Windows 8 Release Preview, we changed the camel-casing rule to handle this
special case in Windows Runtime API Naming guidelines in the expected way.
Specifically, names beginning with three uppercase letters followed by a lowercase
letter will have the first two letters lowercased.
This change only impact a small number of property names in Windows APIs – listed
below.
Windows Runtime JavaScript Before JavaScript After
Windows.Globalization.Fonts.LanguageFontGroup.
UICaptionsFont .uicaptionsFont .uiCaptionsFont
Windows.Globalization.Fonts.LanguageFontGroup.
UIHeadingFont .uiheadingFont .uiHeadingFont
Windows.Globalization.Fonts.LanguageFontGroup.
UINotificationsFont .uinotificationsFont .uiNotificationsFont
Windows.Globalization.Fonts.LanguageFontGroup.
UITextFont .uitextFont .uiTextFont
Windows.Globalization.Fonts.LanguageFontGroup.
UITitleFont .uititleFont .uiTitleFont
‘name’ property of promise cancellation error objects now ‘Canceled’
Brief description:
Change ‘name’ property of promise cancellation error object from ‘Error’ to ‘Canceled’.
Languages JavaScript
Issue and In the Consumer Preview, the error objects produced by cancellation of a promise were slightly
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —60
May 31, 2012
© 2012 Microsoft. All rights reserved.
details different for the Windows Runtime (WinRT) and the Windows Library for JavaScript (WinJS) as
shown below.
In Windows 8 Release Preview, Windows Runtime promises will set the name property of
cancellation errors to ‘Canceled’. Code checking for whether a promise is cancelled can now
consistently switch on the “name” property instead of “description” or “message”.
Property Windows Runtime promise
Windows Library for
JavaScript promise
name Error Canceled
description Canceled Canceled
message Canceled Canceled
JavaScript exceptions returned to Windows Runtime treated as unhandled
Brief description:
A previous change in the Consumer Preview caused Metro style apps using JavaScript to terminate on
unhandled exceptions returned to Web APIs. However, that change did not also include the case where
unhandled exceptions are returned to Windows Runtime callbacks. This Windows 8 Release Preview change
extends the same unhandled exceptions behavior to all exceptions which leave JavaScript. In particular, if a
Windows Runtime delegate invocation calls into JavaScript which throws an exception, this will trigger the
window.onerror handler in user code, and unless onerror suppresses the error reporting, will terminate the app
and issue a Watson report. This matches the existing behavior for exceptions returned to web platform APIs in
Metro style apps using HTML and JavaScript.
Languages JavaScript
Issue and
details
A previous change in the Consumer Preview caused Metro style apps using JavaScript to
terminate on unhandled exceptions returned to Web APIs. However, that change did not
also include the case where unhandled exceptions are returned to Windows Runtime
callbacks. This Release Preview change extends the same unhandled exceptions behavior to
all exceptions which leave JavaScript. In particular, if a Windows Runtime delegate
invocation calls into JavaScript which throws an exception, this will trigger the
window.onerror handler in user code, and unless onerror suppresses the error reporting, will
terminate the app and issue a Watson report. This matches the existing behavior for
exceptions returned to web platform APIs in Metro style apps using HTML and JavaScript.
This change will cause some previously silent failures to become app crashes. App code
which wants to continue to ignore these failures can use either of the techniques that are
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —61
May 31, 2012
© 2012 Microsoft. All rights reserved.
available today for Web APIs:
- Hook up a window.onerror handler to return ‘true’ for certain classes of exceptions,
indicating they should not be treated as unhandled
- Add try/catch around failures and provide appropriate code in the case of failure.
Samples usage
or steps to take
to migrate
code
/////////////////
// Trident Event
/////////////////
window.onmousedown = function (ev) {
throw new Error("Goodbye");
}
// Current: Process is terminated
/////////////////
// Windows Runtime Event
/////////////////
var geolocator = new
Windows.Devices.Geolocation.Geolocator();
geolocator.onpositionchanged = function (ev) {
throw new Error("hello");
}
// Consumer Preview: Process is not terminated
// Release Preview: Process is terminated.
window.MSPointerEvent
MSGestureStart, MSGestureChange and MSGestureEnd require additional developer setup
work
Brief description:
As part of changes to make MSGesture more configurable by developers, we have made a breaking change to
MSGesture that will require apps that consume these events to perform some extra work in order to receive
gestures.
Languages JavaScript
Issue and details MSGestureStart, MSGestureChange and MSGestureEnd are DOM events that are
fired in response to ongoing touch gestures. Until now, all the developer had to
do to receive these events was to register an event listener for them. The implicit
gesture support model that provided this capability has proven to be too
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —62
May 31, 2012
© 2012 Microsoft. All rights reserved.
simplistic and limiting for many scenarios, and the new model requires some
additional overhead work on the part of developers.
Samples usage or steps to
take to migrate code
If an app requires any of these “dynamic” gesture events, the app must new or
allocate an MSGesture object, configure it to fire events at the appropriate target
element, and associate one or more touch contact ids with it.
Developers who want to use gestures should take a close look at the new gesture
model, as it supports many scenarios impossible to implement under the old
model. Among other things, this model allows the developer to have multiple
gestures in play at the same time (simply create two gesture objects, associate
them with targets and contacts, and listen for the events). It also allows a single
contact to participate in more than one gesture, and to target more than one
gesture at a single element (the event listener can differentiate between them by
the gesture id property of the gesture event). Gestures can be targeted
independently of the pointer event hit-test target, and (unlike the old model),
there is no implicit pointer capture for gestures.
For developers simply porting existing code to the new model, the following
boilerplate emulates the old implicit behavior:
var g = new MSGesture();
function onLoad()
{
...
element.addEventListener("MSPointerDown", assignPointer, false); // Do this
for every gesture handling element
...
}
function assignPointer(evt) {
try {
g.target = evt.target; // Emulate old implicit targeting
} catch (err) {} // If gesture has already started, catch and ignore
if (evt.target==g.target) {
g.addPointer(evt.pointerId); // Emulate implicit pointer association
}
}
Developers who want to use gestures should take a close look at the new gesture
model, as it supports many scenarios impossible to implement under the old
model. Among other things, this model allows the developer to have multiple
gestures in play at the same time (simply create two gesture objects, associate
them with targets and contacts, and listen for the events). It also allows a single
contact to participate in more than one gesture, and to target more than one
gesture at a single element (the event listener can differentiate between them by
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —63
May 31, 2012
© 2012 Microsoft. All rights reserved.
the gesture id property of the gesture event). Gestures can be targeted
independently of the pointer event hit-test target, and (unlike the old model),
there is no implicit pointer capture for gestures.
MSGestureTap and MSGestureHold require additional developer setup work
Brief Description: As part of changes to make MSGesture more configurable by developers, we have made a
breaking change to MSGesture that will require apps that consume this event to perform some extra work in
order to receive gestures.
Languages JavaScript
Issue and details MSGestureTap and MSGestureHold are “static” gestures that are fired in response
to tap and “press and hold” touch gestures. Until now, all the developer had to
do to receive these events was to register an event listener for them. The implicit
gesture support model that provided this capability has proven to be too
simplistic and limiting for many scenarios, and the new model requires some
additional overhead work on the part of developers.
Samples usage or steps to
take to migrate code
Developers who are using MSGestureTap and MSGestureHold should consider
moving to simple onclick and oncontextmenu events, as these are independent
of input modality and can be fired by mouse, pen and keyboard activities. If an
app requires MSGestureTap or Hold, the app must new or allocate an MSGesture
object, configure it to fire events at the appropriate target element, and associate
one or more touch contact ids with it.
The following boilerplate emulates the old implicit behavior for developers who
need to do this:
var g = new MSGesture();
function onLoad()
{
...
element.addEventListener("MSPointerDown", assignPointer, false); // Do this
for every gesture handling element
...
}
function assignPointer(evt) {
try {
g.target = evt.target; // Emulate old implicit targeting
} catch (err) {} // If gesture has already started, catch and ignore
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —64
May 31, 2012
© 2012 Microsoft. All rights reserved.
if (evt.target==g.target) {
g.addPointer(evt.pointerId); // Emulate implicit pointer association
}
}
MSGesture transforms now report delta transforms
Brief description:
The DOM MSGestureStart/Change/End events support properties (rotation, scale and translation) that describe
an ongoing interactive manipulation gesture. Going forward, there properties provide a delta from the
previous value rather than a cumulative transform from the beginning of the gesture.
Languages JavaScript
Issue and details Common scenarios for gestures in Metro style apps written using JavaScript and
HTML typically require applying the gesture transform to an elements position
and orientation within a container element. A simple coding technique for this is
to get the transform representing the current position and orientation and
update it by concatenating it with the gesture transform. For such a scenario, the
delta transform is easier to use since it doesn’t require the app to remember the
initial positioning transform from the beginning of the interaction. In addition,
the cumulative transforms provided by the gesture recognition engine are
conditioned by a gesture pivot point offset which itself changes throughout the
interaction. Using deltas enables apps to take that change into account.
Samples usage or steps to
take to migrate code
If a developer is already using the gesture transform to position content, he will
need to update that code to consume a delta rather than cumulative transform.
We recommend using code patterns based on MSCSSMatrix such as:
function manipulateElement(e) {
var m = new MSCSSMatrix(e.target.style.msTransform); //Get the
current xform
e.target.style.msTransform = m.
translate(e.offsetX,e.offsetY). //Move the
transform origin under the gesture pivot point
rotate(e.rotation*180/Math.PI). //Apply R
scale(e.scale). //Apply S
translate(e.translationX,e.translationY). //Apply T
translate(-e.offsetX,-e.offsetY); //Move the
transform from the gesture pivot point
}
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —65
May 31, 2012
© 2012 Microsoft. All rights reserved.
Limiting msReleasePointerCapture DOM API to the current markup
Brief description:
The DOM API msReleasePointerCapture can now only be called within the scope of the same markup as the
capturing element.
Languages JavaScript
Issue and details The DOM API msReleasePointerCapture can now only be called within the scope
of the same markup as the capturing element.
Samples usage or steps to
take to migrate code
Developers should not need to release capture on contacts that have been
captured by an element in a different markup.
Note to writers: this is a security measure. I’m not sure if there are guidelines for
discussing changes that reflect security hardening (since such discussion may
stimulate attackers into giving heightened scrutiny to the change.)
Deprecating DOM event method getPointerList
Brief description:
We are removing a DOM pointer event method
Languages JavaScript
Issue and details DOM pointer events have a method property getPointerList() which can be called
to get information about all the pointers active within the app. Since some of
these pointers may be being used to drive markup in a different security context,
there is a potential information disclosure issue here. The method is being
removed from the Pointer event.
Samples usage or steps to
take to migrate code
Developers who want to track points within the scope of a particular security
context such as a markup, can do so by tracking pointer events at the root node
during their bubble phase.
Deprecating MSGestureDoubleTap
Brief description:
The DOM MSGestureDoubleTap event has been deprecated, since the browser now consumed double-tap
interactions for purposes of zooming.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —66
May 31, 2012
© 2012 Microsoft. All rights reserved.
Languages JavaScript
Issue and details MSGestureDoubleTap was a DOM event. Since the browser now uses double-tap
for purposes of invoking quick zoom, the event has been deprecated.
Samples usage or steps to
take to migrate code
Developers who need a secondary invocation or activation mechanism like
double-tap can still listen for double-click, which the browser will fire even after
double-tap has been consumed for purposes of quick zoom.
Deprecating MSGestureInit DOM events
Brief description:
The DOM event MSGestureInit is no longer useful, and has been removed.
Languages JavaScript
Issue and details MSGestureInit was an event that was designed to provide developers with an
opportunity to prevent default browser manipulation through touch by calling
preventManipulation() on the gesture event. The browser manipulation feature
has been changed to require the use of CSS decorations to declaratively block
manipulations, and preventManipulation() no longer has any effect. Accordingly,
MSGestureInit no longer serves any purpose and has been removed.
Samples usage or steps to
take to migrate code
Developers who listen for MSGestureInit to prevent manipulations need to move
the CSS declarative model (documented and supported in the Consumer Preview
release.) Any MSGestureInit handlers should be removed.
Deprecating msGetPointerCapture DOM API
Brief description:
We are removing an API which the app can emulate if necessary.
Languages JavaScript
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —67
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and details The DOM API msGetPointerCapture was intended to allow the app to determine
which, if any, element had captured a particular touch contact by calling the
msSetPointerCapture API. This is a “convenience” API which the app can easily
emulate if needed.
Samples usage or steps to
take to migrate code
Developers who need to keep track of which element has captured the pointer
can emulate this functionality by handling MSGotCapture events at the root node
of the tree during their bubble phase.
Deprecating MSPointerXXX.preventMouseEvents()
Brief description:
The DOM events MSPointerDown/Update/End used to support a method preventMouseEvents() that would tell
the browser implementation not to fire corresponding mouse events for this input event. This has been
deprecated in favor of the more generic preventDefault() method.
Languages JavaScript
Issue and details HTML/JavaScript apps have two ways to listen for locator input events in
Windows 8. The simplest way is to listen for unified MSPointer events, which are
fired by either mouse, pen or touch input; but for web compatibility purposes, we
also continue to support mouse events, which, by default, are also fired after
MSPointer events are fired (a process called pointer to mouse promotion).
Developers who listen for both classes of events may want to selectively prevent
the firing of mouse events when the event has been handled as a MSPointer
event. For example, a simple implementation of a checkbox UI could listen for
either pointer down and up, or for mouse down and up. However, it would not
want to toggle the state of the checkbox for both, since it would be toggled once
while handling the MSPointer event, and toggled again (undoing the first toggle!)
while handling the mouse event.
preventMouseEvents() was a method that the developer could use to achieve the
goal of suppressing mouse events; this method has been deprecated in favor of
the more generic browser preventDefault() method.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —68
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples usage or steps to
take to migrate code
Developers who use preventMouseEvents() should consider migrating to
preventDefault(). In some cases the developer may not want to prevent all
browser default processing, but may need to prevent mouse events. In that case,
we recommend moving to only handling MSPointer events.
In rare cases, developers may need to provide both a mouse-based
implementation (for example, to run downlevel where pointer events are not
available) and a pointer-based implementation. In those cases, we recommend
detecting the availability of pointer events at page load time, and based on that
availability, installing either a set of pointer event handlers, or a set of mouse
event handlers, but not both at the same time.
New “isPrimary” property on MSPointer events (impacts use of initPointerEvent method)
Brief description:
DOM MSPointer events now support an additional Boolean property, evt.isPrimary, which tells you whether the
event is coming from the primary contact in a multi-touch interaction. This can be useful when the desired UX
uses the first contact down (the primary pointer) to condition how other contacts should be processed by the
app. Developers who synthesize MSPointer events from JavaScript by using the initPointerEvent method need
to include this new property as an input argument.
Languages JavaScript
Issue and details Developers processing multi-touch interactions are sometimes interested in
treating the first contact down differently than the remaining contacts. This
“primary” contact is the only multi-touch contact that will be converted to a
mouse input event by Trident default processing. The new DOM event property
evt.isPrimary returns true or false to enable the developer to make this
distinction.
Developers who synthesize MSPointer events using the method initPointerEvent
need to include the isPrimary flag as an input argument.
Samples usage or steps to
take to migrate code
If you use the initPointerEvent to synthesize MSPointer events, you will need to
include the isPrimary flag as an additional input argument. Here is the updated
syntax and argument list for that method:
Syntax
var retval = MSPointerEvent.initPointerEvent(typeArg, canBubbleArg,
cancelableArg, viewArg, detailArg, screenXArg, screenYArg, clientXArg,
clientYArg, ctrlKeyArg, altKeyArg, shiftKeyArg, metaKeyArg,
buttonArg, relatedTargetArg, offsetXArg, offsetYArg, widthArg,
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —69
May 31, 2012
© 2012 Microsoft. All rights reserved.
heightArg, pressure, rotation, tiltX, tiltY, pointerIdArg, pointerType,
hwTimestampArg, isPrimary);
Parameters
typeArg through h2TimestampArg are unchanged; the only new parameter is the
last one, isPrimary:
isPrimary [in]
Type: boolean
Indicates whether this is the primary pointer that is used to control the
mouse position in a multi-touch scenario.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —70
May 31, 2012
© 2012 Microsoft. All rights reserved.
.NET
Blocking dynamic invocation of nonpublic members in Metro style apps
These changes only apply to Metro style apps. Classic .NET apps are unaffected.
“Dynamic invocation” will refer in this context to:
Using reflection APIs such as method/constructor Invoke, Get/Set property or field values, and
adding/removing event handlers
Light-weight code generation or Expression tree construction scenarios where methods are called,
objects are instantiated via certain constructors, properties, fields, or event handlers are accessed; or
where types are used in formal parameter lists or return signatures
Reflection Emit where types are inheriting from certain types
Invoking via the dynamic keyword
What’s changing
Dynamic invocation will be blocked when APIs not present in the public surface area for Metro style apps,
including Portable Library, are used. Additionally, we are blocking unsafe and marshaling APIs.
This is not affecting third party APIs, nor Windows Runtime APIs (1st or 3rd party)
Impact
Customer code attempting to invoke APIs not in the public area for Metro style apps will fail at run time. The
exception being thrown is InvalidOperationException
A few corner cases involving the use of the dynamic keyword are additionally impacted. These are:
Calling members that are public in implementation, but not in the pulic surface area for Metro style apps,
when such member is an override of a member on a public Metro style apps type or an implicit interface
implementation of a Metro style apps public interface. For example:
dynamic d = myDelegate.BeginInvoke(…);
in the preceding example, myDelegate is some delegate. The underlying type of d is
System.Runtime.Remoting.Messaging.AsyncResult. This type is not public for Metro style apps but public in
the underlying implementation. However, BeginInvoke types it as IAsyncResult, which the above type
implements *implicitly*. The following line will now fail:
d.IsCompleted
Had AsyncResult implemented IAsyncResult *explicitly*, the preceding call would have failed because of the
introduction of the dynamic language feature, due to an existing bug in the C# dynamic binder.
Similar to the above, when the member is an override. For example:
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —71
May 31, 2012
© 2012 Microsoft. All rights reserved.
MethodInfo mi =
typeof(object).GetMethod("Equals", new Type[] {typeof(object)});
ParameterInfo pi = mi.GetParameters()[0];
dynamic value = pi.DefaultValue; //this returns DBNull, which is not in
the Metro style apps API
value.ToString(); //this will fail
Mitigation/workaround
When the result of an invocation to a dynamic object is known to be of some interface type, cast to that
interface first, in order to avoid the existing bug in the binder, as well as the potential that the
implementation of the interface is implicit, case in which the limitation introduced by this feature can be
also avoided.
When the result of an invocation to a dynamic object is known to be of some base type with a known
member, cast first to that base type. In particular, for ToString() calls, cast to object.
[WinMDExp] Use WriteOnlyArray/readOnlyArray for arrays and blocks usage of In/Out for
other cases
What’s changing
1. When using WinMDExp to export methods with array parameters, you’ll need to mark these
parameters with either [System.Runtime.InteropServices.WindowsRuntime.ReadOnlyArray] or
[System.Runtime.InteropServices.WindowsRuntime.WriteOnlyArray]. The exception to this rule is when
there is a reasonable default , such as returning an array, or passing array out by reference, and in
those case the default will be automatically applied without the need to mark with attributes.
2. [ReadOnlyArray] means the contents of your array parameter will only be read in the function
implementation, while [WriteOnlyArray] means the contents of your array parameter can only be
written to in the function implementation. Note that the usage of the array parameter is not enforced
by the compiler, and the attribute value is only used when crossing language/apartment boundaries,
where marshaling are required.
3. [System.Runtime.InteropServices.InAttribute] and [System.Runtime.InteropServices.OutAttribute] are
now blocked, except when passing parameter as [Out] by reference, such as <Out()> ByRef in Visual
Basic.
Impact
WinMDExp will fail to export following code:
C#
public sealed class Test
{
// Must mark [ReadOnlyArray] / [WriteOnlyArray]
public void Func(int[] args)
{
}
// [In] is not supported anymore
public void Func2([In] int[] args)
{
}
// Please use [WriteOnlyArray] or ‘out’ modifier
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —72
May 31, 2012
© 2012 Microsoft. All rights reserved.
public void Func3([Out] int[] args)
{
}
}
Visual Basic Public Not Inheritable Class Test
{
` Must mark [ReadOnlyArray] / [WriteOnlyArray]
Public Sub Func(ByVal args as Integer())
End Sub
` [In] is not supported anymore
Public Sub Func2(<In> args as Integer())
End Sub
` Please use <WriteOnlyArray> or <Out()> ByRef modifier
Public Sub Func3(<Out> ByVal args as Integer)
End Sub
End Class
Passing arrays out by reference or returning arrays are not affected. Following code can still be exported by
WinMDExp:
C# public sealed class Test
{
public int[] Func(out int[] outArray)
{
// …
}
}
Visual Basic Public Not Inheritable Class Test
Public Func(<Out()> ByRef outArray as Integer()) as Integer()
…
End Func
End Class
For non-array parameters, usages of [In] / [Out] are also blocked by this change, except for <Out()> ByRef in
Visual Basic.
Mitigation
For impacted scenarios (see above), you’ll need to explicitly mark your array parameters as [ReadOnlyArray] or
[WriteOnlyArray] :
C#
using System.Runtime.InteropServices.WindowsRuntime;
public sealed class Test
{
public void Func([ReadOnlyArray] int[] args)
{
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —73
May 31, 2012
© 2012 Microsoft. All rights reserved.
}
}
Visual Basic
Imports System.Runtime.InteropServices.WindowsRuntime;
Public NotInheritable Class Test
Public Sub Func(<ReadOnlyArray> args as Integer())
End Sub
End Class
If you have any existing code that explicitly use [In]/[Out] attribute, please remove [In] attribute from your code,
and replace [Out] attribute with either ‘out’ modifier in C#, or <Out()> ByRef in Visual Basic.
[WinMDExp] Two minor breaking changes
There are two possible breaking changes due to recent bug fixes in WinMDExp:
Optional parameters – we issue a warning now when you use those, since the value will not show up for
JavaScript and C++ callers. If you built with warnings as errors, then you may see an error. The mitigation is that
you can pass the warning number to winmdexp via the /nowarn flag in order to stop the warning from firing.
Custom Attributes – we used to incorrectly generate non-functional custom attributes via winmdexp. We’ve
blocked their generation since 3rd party custom attribute generation isn’t a scenario we support. A scan of all
Marketplace apps shows that none of them were trying to generate a custom attribute, which makes sense
since the attributes themselves didn’t get generated correctly in metadata.
Reduce the .NET surface area to remove unnecessary access points to memory
What’s changing:
The following list of .NET APIs are no longer be supported for use in Metro style apps. For the complete list of
supported APIs, .NET for Metro style apps.
Impact:
These are the API's being removed:
M:System.Runtime.InteropServices.Marshal.BindToMoniker(System.String)
M:System.Runtime.InteropServices.Marshal.CleanupUnusedObjectsInCurrentContext
M:System.Runtime.InteropServices.Marshal.GetActiveObject(System.String)
M:System.Runtime.InteropServices.Marshal.GetComSlotForMethodInfo(System.Reflection.MemberInfo)
M:System.Runtime.InteropServices.Marshal.GetEndComSlot(System.Type)
M:System.Runtime.InteropServices.Marshal.GetMethodInfoForComSlot(System.Type,System.Int32,System.Runti
me.InteropServices.ComMemberType@)
M:System.Runtime.InteropServices.Marshal.NumParamBytes(System.Reflection.MethodInfo)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —74
May 31, 2012
© 2012 Microsoft. All rights reserved.
T:System.Runtime.InteropServices.ManagedToNativeComInteropStubAttribute
M:System.Runtime.InteropServices.ManagedToNativeComInteropStubAttribute.#ctor(System.Type,System.Strin
g)
P:System.Runtime.InteropServices.ManagedToNativeComInteropStubAttribute.ClassType
P:System.Runtime.InteropServices.ManagedToNativeComInteropStubAttribute.MethodName
M:System.Runtime.InteropServices.ManagedToNativeComInteropStubAttribute.get_ClassType
M:System.Runtime.InteropServices.ManagedToNativeComInteropStubAttribute.get_MethodName
T:System.Runtime.InteropServices.ICustomMarshaler
M:System.Runtime.InteropServices.ICustomMarshaler.CleanUpManagedData(System.Object)
M:System.Runtime.InteropServices.ICustomMarshaler.GetNativeDataSize
M:System.Runtime.InteropServices.ICustomMarshaler.MarshalManagedToNative(System.Object)
F:System.Runtime.InteropServices.UnmanagedType.CustomMarshaler
T:System.Runtime.InteropServices.StandardOleMarshalObject
M:System.Runtime.InteropServices.StandardOleMarshalObject.#ctor
P:System.RuntimeFieldHandle.Value
M:System.RuntimeFieldHandle.get_Value
P:System.RuntimeMethodHandle.Value
M:System.RuntimeMethodHandle.GetFunctionPointer
M:System.RuntimeMethodHandle.get_Value
P:System.RuntimeTypeHandle.Value
M:System.RuntimeTypeHandle.get_Value
M:System.Runtime.InteropServices.ICustomMarshaler.CleanUpNativeData(System.IntPtr)
M:System.Runtime.InteropServices.ICustomMarshaler.MarshalManagedToNative(System.Object)
M:System.Runtime.InteropServices.ICustomMarshaler.MarshalNativeToManaged(System.IntPtr)
M:System.Runtime.InteropServices.Marshal.GetComInterfaceForObjectInContext(System.Object,System.Type)
M:System.Runtime.InteropServices.Marshal.GetExceptionPointers
M:System.Runtime.InteropServices.Marshal.GetIDispatchForObject(System.Object)
M:System.Runtime.InteropServices.Marshal.GetIDispatchForObjectInContext(System.Object)
M:System.Runtime.InteropServices.Marshal.GetIUnknownForObjectInContext(System.Object)
M:System.Runtime.InteropServices.Marshal.GetTypeForITypeInfo(System.IntPtr)
M:System.Text.Decoder.Convert(System.Byte*,System.Int32,System.Char*,System.Int32,System.Boolean,System.I
nt32@,System.Int32@,System.Boolean@)
M:System.Text.Decoder.GetCharCount(System.Byte*,System.Int32,System.Boolean)
M:System.Text.Decoder.GetChars(System.Byte*,System.Int32,System.Char*,System.Int32,System.Boolean)
M:System.Text.Encoder.Convert(System.Char*,System.Int32,System.Byte*,System.Int32,System.Boolean,System.In
t32@,System.Int32@,System.Boolean@)
M:System.Text.Encoder.GetByteCount(System.Char*,System.Int32,System.Boolean)
M:System.Text.Encoder.GetBytes(System.Char*,System.Int32,System.Byte*,System.Int32,System.Boolean)
M:System.Text.Encoding.GetByteCount(System.Char*,System.Int32)
M:System.Text.Encoding.GetBytes(System.Char*,System.Int32,System.Byte*,System.Int32)
M:System.Text.Encoding.GetCharCount(System.Byte*,System.Int32)
M:System.Text.Encoding.GetChars(System.Byte*,System.Int32,System.Char*,System.Int32)
M:System.Text.UnicodeEncoding.GetByteCount(System.Char*,System.Int32)
M:System.Text.UnicodeEncoding.GetBytes(System.Char*,System.Int32,System.Byte*,System.Int32)
M:System.Text.UnicodeEncoding.GetCharCount(System.Byte*,System.Int32)
M:System.Text.UnicodeEncoding.GetChars(System.Byte*,System.Int32,System.Char*,System.Int32)
M:System.Text.UTF8Encoding.GetByteCount(System.Char*,System.Int32)
M:System.Text.UTF8Encoding.GetBytes(System.Char*,System.Int32,System.Byte*,System.Int32)
M:System.Text.UTF8Encoding.GetCharCount(System.Byte*,System.Int32)
M:System.Text.UTF8Encoding.GetChars(System.Byte*,System.Int32,System.Char*,System.Int32)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —75
May 31, 2012
© 2012 Microsoft. All rights reserved.
.NET Core Profile (Metro style apps) API changes
What's changing:
The following namespaces have been removed from the Metro style apps API:
System.ComponentModel.Composition
System.ComponentModel.Composition.Hosting System.ComponentModel.Composition.Primitives
System.ComponentModel.Composition.Registration
Hide IPropertyValue and IReferenceArry<T>
What’s changing:
The .NET Metadata Adapter will no longer expose two types which are treated specially by Windows Runtime:
IPropertyValue and IReferenceArray.
These types were never meant to be exposed. Currently, it is possible for managed developers to write code
using these types which breaks both the CLR and Windows Runtime type systems. This leads to undefined
behavior in cross language scenarios.
Impact:
Minimal. Code that implemented this interfaces almost certainly did so accidently (these are the only cases
we’ve seen) and the code frequently wouldn’t work correctly. For example, IPropertyValue today cannot be
correctly dispatched against in managed code and it cannot be correctly implemented by managed code.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —76
May 31, 2012
© 2012 Microsoft. All rights reserved.
Visual C++
Platform::Array^ input parameters need to be marked as const
Brief description:
Developers will need to explicitly mark Platform::Array^ input parameters in functions and property as const.
This is because the corresponding metadata need to be marked as [in] and not [in,out]. No changes are needed
for output Platform::Array^ parameters or for Platform::Array^ return types. The compiler will emit clear errors
with the changes that need to be made to the source code.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
error C3952: 'Platform::Array<__TArg> ' : Windows Runtime does not support 'in/out' arrays. Use 'const Array<>^ for 'in' and WriteOnlyArray for 'out' on public APIs.' with [ __TArg=Platform::String ^ ]
Samples usage or
steps to take to
migrate code
Add const keyword as needed, like in the example below (the added keyword are in
green):
public /*or private*/ ref class R1 {
public:
void foo(Array<int>^ a) {} // ERROR: Windows Runtime does not
support 'in/out' arrays. Use 'const Array<>^ for 'in' and
WriteOnlyArray for 'out' on public APIs.'
void foo(const Array<int>^ a) {} // ok
protected:
int bar(int i, String^ s, Platform::Array<bool>^) { return 3; }
// ERROR: Windows Runtime does not support 'in/out' arrays. Use 'const
Array<>^ for 'in' and WriteOnlyArray for 'out' on public APIs.'
int bar(int i, String^ s, const Platform::Array<bool>^) {
return 3; } // ok
property Platform::Array<String^>^ MyArray {
void set(Array<String^>^ newArr) // ERROR: Windows
Runtime does not support 'in/out' arrays. Use 'const Array<>^ for 'in'
and WriteOnlyArray for 'out' on public APIs.'
void set(const Array<String^>^ newArr) // ok
{
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —77
May 31, 2012
© 2012 Microsoft. All rights reserved.
m_arr = ref new Array<String^>(newArr);
}
Array<String^>^ get()
{
return m_arr;
}
}
};
Protected fields are not permitted on ref classes
Brief description:
Fields which may be exposed to metadata in public or private classes with protected accessibility are
disallowed, as they would result in invalid Windows Runtime metadata. This is a more specific case of the
general “no non-ABI permitted types visible to metadata” breaking change from Consumer Preview Update but
was not properly diagnosed by the compiler in the case of protected fields. This bug in the compiler has been
fixed, resulting in this breaking change.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
Error: a non-value type cannot have any public data members
Samples usage or
steps to take to
migrate code
Mark fields as private protected:
public ref class DirectXBase abstract
{
public:
virtual void Render() = 0;
virtual void Present();
internal:
DirectXBase();
protected: // Error: a non-value type cannot have any public data
members
private protected: // ok
Windows::UI::Core::CoreWindow^ m_window;
Microsoft::WRL::ComPtr<ID2D1Bitmap1>
m_d2dTargetBitmap;
D3D_FEATURE_LEVEL m_featureLevel;
Windows::Foundation::Size
m_renderTargetSize;
Windows::Foundation::Rect m_windowBounds;
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —78
May 31, 2012
© 2012 Microsoft. All rights reserved.
float m_dpi;
};
“Private protected” means that the field is treated as protected within this
component, and is private externally (that is, not visible across metadata).
Nested types are not permitted in private ref classes
Brief description:
Nested type definitions (classes/enums/etc) cannot be metadata-exposed (public or protected) in private
classes. This restriction was previously in place for public classes, but should have existed for private classes as
well; however there was a compiler bug which caused the compiler to not issue a diagnostic in this case. This
bug has been fixed, resulting in a breaking change.
Languages C++
Issue and details Compilation will fail with errors similar to the following:
error C3989: 'R::E' : a nested type cannot be public
Samples usage or
steps to take to
migrate code
Mark nested types as internal or private:
/*public*/ ref class R sealed { //public: internal: /* or private */ enum class E {a, b}; };
Virtual methods need to be explicitly specified as ‘virtual’ (and ‘override’ if needed)
Brief description:
Developers will need to state explicitly whether a method is virtual and whether it overrides a base class
method.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
warning C4488: 'FooClass::Func' : requires 'virtual' keyword to implement the
interface method 'IFoo::Func'
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —79
May 31, 2012
© 2012 Microsoft. All rights reserved.
error C3766: 'FooClass' must provide an implementation for the interface method
'void IFoo::Func(void)'
error C4492: 'BarClass::Func' : matches base ref class method 'FooClass::Func', but is
not marked 'override'
Samples usage or
steps to take to
migrate code
Add virtual and override keywords as needed, like in the example below (the added
keyword are in green):
interface class IFoo { void Func(); }; ref struct FooClass abstract: IFoo { virtual void Func(); }; ref struct BarClass sealed: FooClass { virtual void Func() override; };
Non-Windows Runtime C++ exceptions will fail-fast when reaching the language
boundary (rather than turning into E_FAIL)
Brief description:
When a C++ exception (e.g. std::exception) reaches the C++ language boundary, it will bring the process down.
The intent is to have developers handle in their code any non-Windows Runtime exceptions that they expect,
and recover from such exceptions. If an exception is not handled (for example, in a truly exceptional case that
the app cannot recover from) we provide meaningful crash dumps. Platform::Exception type will work as usual.
Languages C++
Issue and details You will not see a compilation problem, but if you do not specifically handle C++
exception like std::exception, you will see the program either crash in the debugger
while debugging or create a crash dump as close to the failure as possible.
Samples usage or
steps to take to
migrate code
When the app logic expects an exception and can recover from it, surround it with a
try/catch that catches the specific exception and take corrective action to leave the
app in a valid stat and return a Platform::Exception type where you expect that C++
code may throw exceptions specific to C++.
try { // user code here
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —80
May 31, 2012
© 2012 Microsoft. All rights reserved.
} catch (exception& e) { // new code here // usually you want to translate the C++ exception // to the appropriate Platform::Exception }
Public ref classes need to be marked as either ‘sealed’ or have a non-public constructor
Brief description:
Constructors of unsealed ref classes cannot be ‘public’. They can only be ‘internal’ (‘public private’), ‘private’ or
‘protected private’. If an unsealed class only has compiler-generated constructors, the compiler will implicitly
generate the constructor as ‘internal:’.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
error C2456: 'Foo' an unsealed ref class cannot have a public visible constructor.
Seal the class, or specify constructor as 'internal', 'protected private' or 'private'
instead.
Samples usage or
steps to take to
migrate code
(a) If your class was not meant to be a base class, do mark the class as “sealed” (see
added keyword in green):
public ref class Foo sealed
{
public:
Foo();
};
(b) If you want to allow other C++ ref classes in the same compilation unit to inherit
from the class and if the derived classes don’t need to be public, simply remove
public from the base class:
public ref class Foo
{
};
ref class Bar: Foo
{
};
(c) If you still want to allow other C++ ref classes in the same compilation unit to
inherit from the class and one or more of the derived classes has to be public, mark
the constructor of the base class as internal. This will allow C++ in-module
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —81
May 31, 2012
© 2012 Microsoft. All rights reserved.
derivation, and output both the base class and derived class to the .winmd.
However, since the constructor of the base is private, the base class will be neither
activatable, nor composable from outside the module (i.e. the base class becomes a
NARC – Non-Activatable-Runtime-Class):
public ref class Foo
{
// in case no constructor is provided, the implicit
// constructor will be internal
internal:
Foo();
};
public ref class Bar: Foo
{
};
Newslot methods are not allowed in interface classes or ref classes (either implicitly or
explicitly by using the ‘new’ keyword)
Brief description:
We’re introducing some limitations around hide-by-sig methods in derived classes and methods marked with
“new”. We’re reserving this “newslot” syntax for future releases.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
error C3660: 'IBar::Func' : hides inherited member 'IFoo::Func'
error C3659: 'BarClass::Func' : override specifier 'new' is not supported
Samples usage or
steps to take to
migrate code
The recommended mitigation is to avoid introducing newslot methods in
further derived types. Do rename your methods if you want to introduce a
new version of the method.
Private/internal ref classes need to follow the same authoring restrictions as public ref
classes
Brief description:
Compiler will enforce that non-public Windows Runtime types follow the same authoring rules as public ones.
This means that compiler will no longer allow, for example, public fields or public methods that use non-
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —82
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows Runtime typed parameters. These constructs are still legal as long as they are made internal.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
error C3987: 'func': signature of public member contains native type 'type'
error C3984: 'Foo' : a non-value type cannot have any public data members
Samples usage or
steps to take to
migrate code
Mark all the types and methods which use non-Windows Runtime types as
“internal”, just as you would do with a “public” ref class. If you have this code:
private ref struct FooClass { public: int _i; void func(void** o);
};
You will need to add the “internal” keyword:
private ref struct FooClass { internal: int _i; void func(void** o);
};
Instances of types with the marshaling behavior != Agile used as field or global will issue a
warning recommending use of Platform::Agile<T>
Brief description:
Class members and globals of a type that isn’t advertised in metadata as agile (i.e. marked with a
[MarshalingBehavior(Standard)] or [MarshalingBehavior(none)]) will cause a compile time W3 warning.
Languages C++
Issue and details Compilation emit warning level 3 similar to the following:
warning C4451: 'Foo::_gr' : Usage of ref class 'Windows::UI::Input::GestureRecognizer'
inside this context can lead to invalid marshaling of object across contexts
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —83
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples usage or
steps to take to
migrate code
Consider using Platform::Agile<T> (from agile.h) instead of T^ to correctly marshal
the instance in case it may get called from different apartments.
Code that looks like this:
Windows::UI::Input::GestureRecognizer^ global; ref class Foo sealed { public: int Test(); internal: Windows::UI::Input::GestureRecognizer^ _gr; };
Should be converted to:
#include <agile.h> Platform::Agile<Windows::UI::Input::GestureRecognizer> global; ref class Foo sealed { public: int Test(); internal: Platform::Agile<Windows::UI::Input::GestureRecognizer> _gr; };
Consider silencing the warning only if you can guarantee that the component will
never be accessed from another apartment than the one it was created in.
Public templated ref classes, its explicit instantiations and public templated methods are
not supported
Brief description:
Previously legal but causing unexpected metadata generation, publishing instantiated templates (classes or
methods) to metadata is not legal anymore.
Languages C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —84
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and details Compilation will fail with warnings and errors similar to the following:
error C3401: 'Foo' : invalid assembly access specifier - only 'private' is allowed on
class templates
Samples usage or
steps to take to
migrate code
If you have code like this:
template <class T> public ref class Foo { };
consider marking the class as private:
template <class T> private ref class Foo { };
You can use the pointer-to-implementation (Pimpl) pattern to embed private
templated ref classes into public ref classes, if needed.
Can no longer derive from Platform::Exception
Brief description:
Inheriting from Platform::Exception (even if the class is not sealed) is specifically inhibited in C++/CX.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
error C3125: 'MyException' : type cannot directly or indirectly derive from
'Platform::Exception'
Samples usage or
steps to take to
migrate code
No mitigation. You cannot inherit from Platform::Exception.
Explicit [Windows::Foundation::Metadata::Guid] attribute cannot be specified anymore on
interfaces or classes (only [uuid] is legal)
Brief description:
Specifying a [Guid(…)] attribute on an interface is not allowed anymore.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —85
May 31, 2012
© 2012 Microsoft. All rights reserved.
Languages C++
Issue and details Compilation will fail with warnings and errors similar to the following:
error C3979: 'IFoo' : use attribute 'uuid' instead of
'Windows::Foundation::Metadata::GuidAttribute'
Samples usage or
steps to take to
migrate code
If you have code like this:
[Windows::Foundation::Metadata::Guid(0x31992907, 0xfeb9, 0x4ab7, 0x83, 0x9f, 0xca, 0x29, 0x2d, 0x28, 0x4f, 0x36)] public interface class IFoo { int Test(); };
Change it to look like this:
[uuid("31992907-FEB9-4AB7-839F-CA292D284F36")] public interface class IFoo { int Test(); };
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —86
May 31, 2012
© 2012 Microsoft. All rights reserved.
Graphics & Gaming
DirectXMath
Windows 8 Release Preview includes DirectXMath version 3.03. The Windows Developer Preview included
DirectXMath version 3.00, and the Windows Consumer Preview included DirectXMath version 3.02.
There were some potentially breaking changes made as part of this new revision.
Steps to migrate
Languages C++, unknown
Issues Build error C2039 when using DirectX::XMMATRIX
For example:
test.cpp(16) : error C2039: ‘m’ is not a member of ‘DirectX::XMMATRIX’ test.cpp(21) : error C2039: ‘_14’ is not a member of ‘DirectX::XMMATRIX’
Resolution DirectXMath inherited the original declaration of XMMATRIX which provided a union:
union
{
XMVECTOR r[4];
struct
{
FLOAT _11, _12, _13, _14;
FLOAT _21, _22, _23, _24;
FLOAT _31, _32, _33, _34;
FLOAT _41, _42, _43, _44;
};
FLOAT m[4][4];
};
This allows individual element access directly with XMMATRIX, but this generates poorly
performing code. Version 3.03 removes the union and leaves only the r vector members
XMVECTOR r[4];
If individual element access is required, either use the correct vector accessor method with .r
such as:
XMMATRIX m;
float a = m._23;
should be:
float a = XMVectorGetZ( m.r[1] );
If several operations on individual elements is being performed on the same XMMATRIX
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —87
May 31, 2012
© 2012 Microsoft. All rights reserved.
instance, then use the matrix equivalent types such as XMFLOAT4X4 to efficiently move it from
a SIMD form to a struct form.
XMFLOAT4X4 tmp;
XMStoreFloat4x4( &tmp, m );
// reference elements in tmp instead of m
NOTE: The original union is still defined when using the scalar version of the math library via the
control define _XM_NO_INTRINSICS_
Languages C++, unknown
Issues Build error C2440 or C2679 when using DirectX::XMFLOAT2, DirectX::XMFLOAT2A,
DirectX::XMFLOAT3, DirectX::XMFLOAT3A, DirectX::XMFLOAT4 or DirectX::XMFLOAT4A
test.cpp(32) : error C2440: ‘initializing’ cannot convert from ‘float [4]’ to ‘DirectX::XMFLOAT4’ Constructor for struct ‘DirectX::XMFLOAT4’ is declared ‘explicit’ test.cpp(40) : error C2679: binary ‘=’ no operator found which takes a right-hand operand of type ‘float [4]’ (or there is no acceptable conversion)
Resolution Most single-parameter constructors in XNAMath/DirectXMath have been marked explicit to
avoid subtle runtime bugs. Version 3.03 marks the last few remaining constructors explicit. If
you have code of the form:
float f[4] = { 1.f, 2.f, 3.f, 4.f };
XMFLOAT4 vec = f;
vec = f;
it should be changed to:
XMFLOAT4 vec(f);
vec = XMFLOAT4(f);
Windows Parental Controls and Game Definition Files (GDF)
Windows 8 Release Preview includes some changes to the Windows Parental Controls ratings systems. If your
app makes use of a Game Definition File Editor (GDF) and has populated game ratings, be sure to update the
GDF accordingly using the latest GDFMaker tool in the Windows SDK
(%WindowsSdkDir%\bin\x86\gdfmaker.exe)
The following ratings systems were added:
Classification Operations Board (Australia)
Department of Justice (Brazil)
Film and Publication Board (South Africa)
Office of Film and Literature Classification (New Zealand)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —88
May 31, 2012
© 2012 Microsoft. All rights reserved.
The artwork for PEGI ratings were updated and support for the “Online” and “Gambling” descriptors was added.
The PEGI-Finland and Office of Film and Literature Classification (Australia) rating systems have been
deprecated and removed. The Finland region now uses the standard PEGI rating system, and Australia now uses
COB.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —89
May 31, 2012
© 2012 Microsoft. All rights reserved.
COM
CoWaitForMultipleHandles function and CoWait_Flags
Brief description:
CoWaitForMultipleHandles function is no longer supported in Metro style apps. In addition the following
CoWait_Flags have been removed:
COWAIT_DISPATCH_CALLS
COWAIT_DISPATCH_WINDOW_MESSAGES
Languages C++
Issue and details CoWaitForMultipleHandles function is no longer supported and the
COWAIT_DISPATCH_CALLS Flag and COWAIT_DISPATCH_WINDOW_MESSAGES
flags have been removed.
Mitigation or Migration
processes
If your code was using CoWaitForMultipleHandles in order to perform a
blocking wait on an ASTA thread that requires reentrancy, you will need to
consider using the Windows Runtime async pattern to offload the work to
process on another thread without blocking the ASTA.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —90
May 31, 2012
© 2012 Microsoft. All rights reserved.
Namespaces
Windows.ApplicationModel.Resources.Core
toString, toFileAsync rename
Languages JavaScript, C++, .NET
Changes:
1. Windows.ApplicationModel.Resources.Core.ResourceCandidate.toString() renamed to
valueAsString as a property.
2. Windows.ApplicationModel.Resources.Core.ResourceCandidate.toFileAsync() renamed to
valueAsFileAsync()
Who is impacted?
Anybody using the ResourceManager to retrieve resources.
Samples:
C# Samples
var map = Windows.ApplicationModel.Resources.Core.ResourceManager.current.mainResourceMap; String string = map.getValue(‘Resources/String1’).valueAsString; StorageFile file = await map.getValue(‘Files/images/logo.png’).valueAsFileAsync();
JavaScript Samples
var map = Windows.ApplicationModel.Resources.Core.ResourceManager.current.mainResourceMap; var string = map.getValue(‘Resources/String1’).valueAsString; map.getValue(‘Files/images/logo.png’).valueAsFileAsync().then(function(file){ });
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —91
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.Devices.Sms
SMS functionality is only available to mobile operator apps and Metro style apps given privileged access by
mobile network operators. Mobile network operators specify privileged apps through service metadata. For
more information on service metadata, see Mobile Broadband SMS.
Windows.Foundation.Collections
PropertySet marshaling behavior is changing from non-agile to agile
Brief description:
The Windows.Foundation.Collections.PropertySet Windows Runtime API’s marshaling behavior is changing
from non-agile to agile.
Languages C++, C#
Issue and details When the PropertySet becomes agile and is used from multiple apartments, event
notifications may now be fired from multiple apartments.
Impact: Developers who use agile notifications may start seeing notifications
delivered by an MTA thread instead of by an (A)STA thread.
Broken Scenario: Developer code in the PropertySet notification callbacks that
directly interacts with UI elements may no longer work. Since these callbacks
may not always execute on an (A)STA (as they previously did), the UI code may
execute in the context of an MTA and fail.
Mitigation or Migration
processes
Update the developer code to:
Option 1: Request for the UI code to execute on the UI thread (i.e.: via
InvokeDispatch)
Option 2: If using C++, use Platform::CallbackContext::Same to specify a non-
agile delegate.
Windows.Globalization
ApplicationPreferences removed
Languages JavaScript, C#, C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —92
May 31, 2012
© 2012 Microsoft. All rights reserved.
Brief description:
There is a small set of changes intended to make the behavior of app language preferences more transparent.
In particular, the default Globalization.Language() constructor is misconstrued as referring to the preferred
current runtime language. It should not be thus understood and will be removed. Instead, apps should use the
ApplicationLanguages class. The breaking changes:
1. The default constructor for Windows.Globalization.Language is removed. You can still construct a
Language object by passing in a language tag.
2. The Windows.Globalization.ApplicationPreferences class is removed. Its sole property
PreferredLanguage, is moved to Windows.Globalization.ApplicationLanguages and renamed
primaryLanguageOverride. This is a writeable property that allows an app to set an override value on
the top language of the app language list.
These are accompanied by a non-breaking change which will expose the current app language list through
Windows.Globalization.ApplicationLanguages.languages
This is a computed list of languages that merges the app’s declared supported languages with the user’s
ranked list of preferred languages. This list (ApplicationLanguages.languages) is the recommended source of
the best current runtime language value(s) preferred by the user. (Note that it will yield the same values as the
language list exposed via Resource Manager in
Windows.ApplicationModel.Resources.Core.ResourceManager.defaultContext.languages).
The new ApplicationLanguages class will also expose a property that gives the app’s declared supported
languages: Windows.Globalization.ApplicationLanguages.manifestLanguages
Who is impacted?
1. Anyone using the default Windows.Globalization.Language() constructor.
2. Anyone using Windows.Globalization.ApplicationPreferences. (Typically you would be using this
class to set a preferred runtime language for your app in response to some expressed user
preference.)
Samples:
JavaScript Samples
Language Constructor Before: // Get current system language var language = new Windows.Globalization.Language(); Language Constructor After (recommended): // Get top user preferred language var topUserLanguage = Windows.System.UserProfile.GlobalizationPreferences.languages[0]; var language = new Windows.Globalization.Language(topUserLanguage);
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —93
May 31, 2012
© 2012 Microsoft. All rights reserved.
Preferred Application language Before: var preferredLanguage = Windows.Globalization.ApplicationPreferences.preferredLanguage; Preferred Application language After: var preferredLanguage = Windows.Globalization.ApplicationLanguage.primaryLanguageOverride;
Calendar.Compare method
Languages JavaScript, C#, C++
Brief description:
The static Compare method in Windows.Globalization for comparing calendar objects will be removed and
replaced by an instance method.
Windows.Globalization.Calendar.Compare(a,b) becomes a.Compare(b).
Also a set of redundant methods are removed and have been supplanted by existing methods:
Previous method Replaced by
toDateTime() getDateTime()
fromDateTime() setDateTime()
.now setToNow()
.minsupported setToMin()
.maxsupported setToMax()
Who is impacted?
Anyone using Windows.Globalization and working with calendar objects (getting, setting, comparing)
Samples:
JavaScript Samples
// Obtain today's date. var calendarDate = new Date(); // Create a calendar based on the current user and set to today’s date. var calendarA = new Windows.Globalization.Calendar(); calendarA.setDateTime(calendarDate); // Create a second calendar and set to that calendar’s min value var calendarB = new Windows.Globalization.Calendar();
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —94
May 31, 2012
© 2012 Microsoft. All rights reserved.
calendarB.setToMin(); // Compare the calendars var number = calendarA.Compare(calendarB);
Windows.Globalization.Fonts
LanguageFontGroup property changes
Languages JavaScript, C++, .NET
Changes:
The Windows.Globalization.Fonts.LanguageFontGroup class has properties that return font recommendations
for a given language for different style/usage categories—each property corresponding to a different
style/usage category. The naming of some of these properties has been changed to provide better consistency
in naming as well as greater clarity:
Old property name New property name
UICaptionsFont UICaptionFont
UINotificationsFont UINotificationHeadingFont
Also, for some combinations of language and a style/usage category, no font recommendation is available. For
example, for the fixed-width text category, font recommendations can be provided for only a small subset of
the scripts supported in Windows. The LanguageFontGroup properties for which this is relevant are:
DocumentAlternate1Font
DocumentAlternate2Font
FixedWidthTextFont
Before this change, if one of these properties is accessed when the language / script passed in the
LanguageFontGroup constructor isn’t supported for that property, an exception would be thrown. The new API
behaviour is that a LanguageFontGroup property will return Null if no font recommendation is available for the
given language/category combination.
Who is impacted?
Anybody who is uses the LanguageFontGroup class and accesses the affected properties.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —95
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples:
C# Samples:
Property name change: Before: LanguageFontGroup lfg = new LanguageFontGroup("hi"); // Hindi LanguageFont captionFont = lfg.UICaptionsFont; LanguageFont notificationHeadingFont = lfg.UINotificationsFont Now: LanguageFontGroup lfg = new LanguageFontGroup("hi"); // Hindi LanguageFont lfCaption = lfg.UICaptionFont; LanguageFont notificationHeadingFont = lfg.UINotificationHeadingFont
Property exception change: Before: LanguageFontGroup lfg = new LanguageFontGroup("hi"); // Hindi LanguageFont lf; try { lf = lfg.FixedWidthFont; } catch (System.Exception e) { if (e.HResult == -2147023727) { // do some fallback } else throw e; } Now: LanguageFontGroup lfg = new LanguageFontGroup("hi"); // Hindi LanguageFont lf = lfg.FixedWidthFont; if (lf == null) { // do some fallback }
JavaScript Samples:
Property name change: Before: var lfg = new Windows.Globalization.LanguageFontGroup("hi"); // Hindi var captionFont = lfg.uiCaptionsFont; var notificationHeadingFont = lfg.uiNotificationsFont Now: var lfg = new Windows.Globalization.LanguageFontGroup("hi"); // Hindi var lfCaption = lfg.uiCaptionFont; var notificationHeadingFont = lfg.uiNotificationHeadingFont
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —96
May 31, 2012
© 2012 Microsoft. All rights reserved.
Property exception change: Before: var lfg = new LanguageFontGroup("hi"); // Hindi var lf; try { lf = lfg.FixedWidthFont; } catch(err) { if (err.number === -2147023727) { // do some fallback } else { throw err; } } Now: var lfg = new Windows.Globalization.LanguageFontGroup("hi"); // Hindi var lf = lfg.FixedWidthFont; if (!lf) { // do some fallback }
Windows.Graphics.Printing
IPrintDocumentPackageTargetFactory and IPrintDocumentPackageStatusEvent are not
accessible to Metro style apps
Brief description:
In documenttarget.idl, only IPrintDocumentPackageTarget is supposed to be for Metro style apps. The rest of
the interfaces: IPrintDocumentPackageTargetFactory and IPrintDocumentPackageStatusEvent are for desktop
apps only. However, all of them were marked as Metro style app interfaces in the idl file. This has been
resolved and the “const” decoration has been removed from
IPrintDocumentPackageTarget::GetPackageTargetTypes. This change introduces a signature change in the
public interface IPrintDocumentPackageTarget.
Lan-
guages
C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —97
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and
details
In documenttarget.idl, only IPrintDocumentPackageTarget is supposed to be for Metro style apps.
The rest of the interfaces: IPrintDocumentPackageTargetFactory and
IPrintDocumentPackageStatusEvent are for desktop apps only. However, all of them were marked
as Metro style app interfaces in the idl file. This has been resolved and the “const” decoration has
been removed from IPrintDocumentPackageTarget::GetPackageTargetTypes. This change
introduces a signature change in the public interface IPrintDocumentPackageTarget.
Samples
usage or
steps to
take to
migrate
code
If apps use ID2D1PrintControl, there is no change needed. The change in the system component
covers the fix.
If apps generate their own XPS OM and call GetPackageTargetTypes, then there is small change for
them:
Before change After change
UINT targetCounts = 0;
Const GUID* targetTypes = NULL;
hr = IPrintDocumentPackageTarget-
>GetPackageTargetTypes(&targetCou
nts, &targetTypes);
UINT targetCounts = 0;
GUID* targetTypes = NULL;
hr = IPrintDocumentPackageTarget->
GetPackageTargetTypes
(&targetCounts, &targetTypes);
…
if (targetTypes)
{
CoTaskMemFree((LPVOID)targetTypes);
}
Additional parameter to pass while creating DXGI surface for printing
Brief description:
While initializing a DXGI surface for printing, in addition to the D3D11_BIND_RENDER_TARGET flag that needs
to be passed, a new flag needs to be passed. The new flag is D3D11_BIND_SHADER_RESOURCE. This change
was made for performance improvement for print preview.
Languages: C++ or C# apps printing via D2D print control
Who is impacted?
1. Native D2D apps that create a DXGI surface directly to print are impacted.
2. Metro style apps written using JavaScript and HTML, that use the standard HTML print path via
MSApp.GetHtmlPrintDocumentSource(), need no change because Trident creates the DXGI surface and
already includes this flag.
3. Metro style apps written using C#, Visual Basic, or C++, and XAML, also do not need to change,
because the framework creates the DXGI surface and already includes the flag
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —98
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples:
C++ Samples
From Direct2DPrintingFromMetroStyleApps Sample in D2DPageRenderer.cpp: void PageRenderer::DrawPreviewSurface( _In_ float width, _In_ float height, _In_ float scale, _In_ D2D1_RECT_F contentBox, _In_ uint32 desiredJobPage, _In_ IPrintPreviewDXGIPackageTarget* previewTarget ) { // We are accessing D3D resources directly without D2D's knowledge, so we // must manually acquire the D2D factory lock. // // Note: it's absolutely critical that the factory lock be released upon // exiting this function, or else the entire app will deadlock. This is // ensured via the following RAII class. D2DFactoryLock factoryLock(m_d2dFactory.Get()); CD3D11_TEXTURE2D_DESC textureDesc( DXGI_FORMAT_B8G8R8A8_UNORM, static_cast<uint32>(ceil(width * m_dpi / 96)), static_cast<uint32>(ceil(height * m_dpi / 96)), 1, 1, D3D11_BIND_RENDER_TARGET | D3D11_BIND_SHADER_RESOURCE ); ... }
CMetroTemplatePrinter object to call StartPrint() method
Brief description:
StartPrint method needs to be called on the CMetroTemplatePrinter to ensure that the JavaScript print
template is initialized and ready to print. This change was made to avoid race condition where the
CMetroTemplatePrinter object in Trident receives printing notifications from the OS before the JavaScript print
template which it serves has had a chance to initialize the necessary event handlers. The call should be made
after the event registration occurs.
Languages: JavaScript apps that print
Who is impacted?
Web apps that use a custom print template to support customized experience for print
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —99
May 31, 2012
© 2012 Microsoft. All rights reserved.
Samples:
JavaScript Custom Print Template Samples:
From PrintSample/js/print-templates/Scenario4.htm: /// <summary> /// Initializes the custom print template. /// </summary> function init() { // Attach Metro style app printing events printer.onpaginate = handlePaginate; printer.onpreviewpage = handlePreviewPage; printer.onprint = handlePrint; printer.onprinttaskoptionchange = handlePrintTaskOptionChange; // Start the preview/printing process printer.startPrint(); oPageStyleClass = findStyleRule(".pagestyle"); oLorStyleClass = findStyleRule(".lorstyle"); // Set the page dimensions setPageLayout(); }
Windows.Management.Deployment
(Minor) Breaking change and new additions to Package Manager Inventory APIs
Brief description:
Fix how a null/empty user SID parameter is interpreted for the following two Package Manager Inventory APIs
that accept a User SID and incorrectly interpret a null/"" user SID value as all-users instead of currently logged
on user.
1. FindPackagesByUserSecurityId
2. FindPackagesByUserSecurityIdNamePublisher
The table below lists the full set of Package Manager APIs available for enumerating Metro style app packages.
The 3 new APIs are in purple, the 2 impacted APIs are in red:
Overload name Interface method name All
users
Requires admin
FindPackage FindPackageByPackageFullName Yes Yes
FindPackages FindPackages Yes Yes
FindPackagesByNamePublisher Yes Yes
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —100
May 31, 2012
© 2012 Microsoft. All rights reserved.
FindPackagesByPackageFamilyName Yes Yes
FindPackageForUser FindPackageByUserSecurityIdPackageFullName No if user != caller
FindPackagesForUser FindPackagesByUserSecurityId No if user != caller
FindPackagesByUserSecurityIdNamePublisher No if user != caller
FindPackagesByUserSecurityIdPackageFamilyName No if user != caller
FindUsers FindUsers Yes Yes
Languages C++, .NET
Issue and details In many Windows APIs, a null user SID parameter implies the current user
while a special Everyone SID (S-1-1-0) indicates all users. These APIs should
do the same. This makes it most convenient to the caller as well as they do
not need to first retrieve the user SID when calling in the context of current
user.
A secondary motivation is that since we are adding new APIs to support
inventorying packages using monikers – PackageFullName and
PackageFamilyName. We would like to implement the right behavior for
null/”” user SID for these new APIs, and also like for this behavior to be
consistent with the existing APIs.
Samples usage or steps
to take to migrate code
Make the following replacements to any code that references these APIs
with a null/"" user SID:
FindPackagesByUserSecurityId
FindPackagesByUserSecurityIdNamePublisher
SID
type Meaning Comments
NULL Specifies the currently logged-
on user.
If you were using null or “” to
enumerate packages for all
users on the machine, replace
it with the special everyone
SID s-1-1-0 or use the
corresponding all-users APIs:
FindPackages,
FindPackagesByNamePublishe
r.
User
SID
Specifies enumeration for a
particular user in the system.
Requires admin privileges, if
SID is not of currently logged-
on user. An example of user
No change required.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —101
May 31, 2012
© 2012 Microsoft. All rights reserved.
SID is "S-1-3-64-2415071341-
1358098788-3127455600-
2561".
s-1-1-0
Specifies enumeration across
all users in the system.
Requires admin privileges.
No change required, s-1-1-0
was not previously
implemented as a way to
enumerate all users.
Windows.Networking.BackgroundTransfer
Windows.Networking.BackgroundTransfer API updates
Brief description:
Languages C++, .NET
Issue and details If you use the
Windows.Networking.BackgroundTransfer APIs, you
must update your code to the following new
names.
BackgroundDownloader
If you used BackgroundDownloader you will need to update your code to the new API.
Previous Name New API
SetRequestBodyFile CreateDownload, CreateDownloadFromFile,
CreateDownloadAsync
SetRequestBodyStreamAsync CreateDownload, CreateDownloadFromFile,
CreateDownloadAsync
BackgroundUploader
If you used BackgroundUploader you will need to update your code to the new API.
Previous Name New API
SetSourceFile CreateUpload
CreateUploadFromStreamAsync
CreateUploadWithFormDataAndAutoBoundaryAsync
CreateUploadWithSubTypeAsync
CreateUploadWithSubTypeAndBoundaryAsync
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —102
May 31, 2012
© 2012 Microsoft. All rights reserved.
SetSourceStreamAsync CreateUpload
CreateUploadFromStreamAsync
CreateUploadWithFormDataAndAutoBoundaryAsync
CreateUploadWithSubTypeAsync
CreateUploadWithSubTypeAndBoundaryAsync
Windows.Networking.NetworkOperators
Service metadata changes
Issue:
All service metadata for mobile broadband in Windows 8 will need to be recreated for the Release Preview
build. This is because there is a change in how the HWID values are encoded and represented in Release
Preview which is a change from the Consumer Preview build.
The HWID values are encoded representations of the SIM’s IMSI, ICCID, or the CDMA provider ID or provider
name values.
Impact:
Because the encoding algorithm has changed between Windows 8 Consumer Preview to Windows 8 Consumer
Preview Update – partners who wish to test their implementation on Windows 8 Consumer Preview Update will
need to create new metadata packages using either:
Metadata authoring tool that comes with Visual Studio Ultimate 2012 RC
HWID generation tool that comes from the Windows Driver Kit (WDK) for Windows 8 Consumer
Preview Update
These tools have been updated to generate the expected HWID values that match the new format that
Windows 8 Release Preview will be using when trying to match the user’s SIM card (or CDMA based modem)
with a metadata experience.
If you have been developing on Windows 8 Consumer Preview Update and Consumer Preview Update 2 builds,
service metadata created on Consumer Preview Update will not work on Consumer Preview Update 2. Service
metadata that was created using Consumer Update 2 will work on Windows 8 Release Preview.
Testing:
The Windows Hardware Developer Center Dashboard will use the Windows 8 Consumer Preview Update 2
HWID encoding algorithm for mobile broadband in the Windows 8 Release Preview. Before this you will not be
able to submit mobile broadband service metadata created in Consumer Preview Update or Consumer Preview
Update 2 to the Windows Hardware Developer Center Dashboard. If you need to test before the next release, it
is recommended that you enable test signing and test locally by placing your metadata package in the device
metadata store.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —103
May 31, 2012
© 2012 Microsoft. All rights reserved.
You will be able to successfully test the end to end download and install process for mobile broadband service
metadata when Release Preview is available. At that time you will be able to use the service metadata you
created with Consumer Preview Update 2 or with Release Preview to submit to the Windows Hardware
Developer Center Dashboard.
Behavior change
If you used IMobileBroadbandDeviceInformation::DeviceId you will need to update your code to the new API.
The property IMobileBroadbandDeviceInformation::DeviceId was changed to return a device instance path. It
previously returned the IMEI (mobile equipment ID) of the mobile broadband device. The IMEI is now exposed
through a new property (MobileEquipmentId).
Removed type
The enum Windows.Networking.NetworkOperators.CellularClass was redundant with
Windows.Devices.Sms.CellularClass. This type in NetworkOperators has been removed. The minority scenarios
where an app needs to compare the value, it can reference the one in Sms.
New properties
The following properties of IMobileBroadbandDeviceInformation provide information about the current
connection on the device.
MobileEquipmentId
RegisteredDataClass
RegisteredProviderId
RegisteredProviderName
The new property IMobileBroadbandDeviceInformation::MobileEquipmentId returns what
IMobileBroadbandDeviceInformation::DeviceId used to.
The following properties of INetworkOperatorNotificationEventDetails have been added to help write
background notifications handlers in multi-carrier networks:
RuleId - Provides the identifier of the provisioned rule that matched and triggered the notification.
SmsMessage - If the transport for the notifications was Sms, returns a message object so that further
SMS message details can be retrieved.
New Method
IMobileBroadbandNetwork::ShowConnectionUI() allows a mobile operator app to open the available
connections Flyout.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —104
May 31, 2012
© 2012 Microsoft. All rights reserved.
Provisioning metadata changes
Provisioning of Wi-Fi Hotspots
In order to reduce the number of WLAN profiles on a system, the schema has been modified to constrict the
number of WLAN profiles and SSIDs which can be provisioned. Carriers are encouraged to instead place
multiple SSIDs per profile.
Carriers with extensive Wi-Fi roaming networks which cannot fit within the new limits may take advantage of
new functionality in the HotspotAuth section of the profile, enabling the hotspot configuration for a
provisioned profile to be inherited by user-created profiles if the user ever manually connects to these
networks. This section can include not only fixed SSIDs, but prefixes matching all SSIDs which begin with a
given string.
Carriers should place their highest-priority and most common SSIDs in the standard WLAN profile. Reserve the
Hotspot Profile SSIDs for less-common SSIDs which most users will not encounter, but which should
authenticate using Wireless Internet Service Provider roaming (WISPr) if a user connects to them.
Core Provisioning
<!-- Wi-Fi info -->
<xs:element name="WLANProfiles" minOccurs="0" maxOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element ref="wlan:WLANProfile" maxOccurs="unbounded" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
WLAN’s SSIDConfig
<xs:element name="SSIDConfig" maxOccurs="256" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="SSID" maxOccurs="256" maxOccurs="25">
<xs:complexType>
...
</xs:complexType>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —105
May 31, 2012
© 2012 Microsoft. All rights reserved.
</xs:element>
<!-- extension point for other namespaces -->
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
HotspotProfile
<xs:element name="HotspotProfile">
<xs:complexType>
<xs:sequence>
<xs:choice>
<xs:sequence>
<xs:element ref="BasicAuth"/>
<xs:element ref="TrustedDomains"/>
</xs:sequence>
<xs:sequence>
<xs:element ref="ExtAuth"/>
<xs:element ref="TrustedDomains" minOccurs="0"/>
</xs:sequence>
</xs:choice>
<xs:element name="UserAgent" minOccurs="0" type="xs:token"/>
<xs:element ref="SSIDConfig" minOccurs="0"/>
<!-- extension point -->
<xs:any processContents="lax" namespace="##other" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —106
May 31, 2012
© 2012 Microsoft. All rights reserved.
</xs:complexType>
</xs:element>
<xs:element name="SSIDConfig">
<xs:complexType>
<xs:sequence>
<xs:element name="SSID" maxOccurs="250">
<xs:complexType>
<xs:choice>
<xs:element name="hex">
<xs:simpleType>
<xs:restriction base="xs:hexBinary">
<xs:minLength value="1" />
<xs:maxLength value="32" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="hexPrefix">
<xs:simpleType>
<xs:restriction base="xs:hexBinary">
<xs:minLength value="4" />
<xs:maxLength value="32" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="name">
<xs:simpleType>
<xs:restriction base="xs:string">
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —107
May 31, 2012
© 2012 Microsoft. All rights reserved.
<xs:minLength value="1" />
<xs:maxLength value="32" />
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="namePrefix">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:minLength value="4" />
<xs:maxLength value="32" />
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
Validity and Ordering of Message Parsing Fields
The schema has been updated to disallow invalid combinations of fields (UsageTimestamp is required if any
other Usage* field is specified). As a by-product of XSD, this imposes a specific ordering on the Fields as
declared in the XML. The fields may still occur in any order in the SMS message being parsed.
Added field “RuleID” on Message Rules
The Rule ID allows an operator to assign a token to a message rule. Upon receipt of a message of this type, the
Rule ID is passed back to the operator to assist them in identifying the message and how it should be parsed.
This allows the Operator App not to duplicate the parsing and identification logic which Windows has already
applied. (See “RuleId” attribute added to INetworkOperatorNotificationEventDetails, below.)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —108
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.Networking.Proximity
Windows.Networking.Proximity.PeerFinder renames
Brief description:
Some PeerFinder property renames, remove ProximityStreamSocket in favor of StreamSocket, including moving
SessionKey to StreamSocketInformation.
Languages JavaScript, C++, .NET
Issue and details Some PeerFinder property renames, remove ProximityStreamSocket in favor of
StreamSocket, including moving SessionKey to StreamSocketInformation.
Samples usage or
steps to take to
migrate code
Windows.Networking.Proximity.ProximityStreamSocket is being removed. Instead use
Windows.Networking.Sockets.StreamSocket
Windows.Networking.Proximity.ProximityStreamSocket.SessionKey is being moved.
Instead use Windows.Networking.Sockets.StreamSocketInformation.SessionKey.
Windows.Networking.Proximity.ProximityStreamSocket.SocketType is being removed.
This had limited value and would be difficult to move to StreamSocketInformation.
Windows.Networking.Proximity.PeerFinder.AllowTcpIp is being renamed to
Windows.Networking.Proximity.PeerFinder.AllowInfrastructure
When an app is launched by proximity, a LaunchArgs string is passed via
LaunchActivatedEventArgs.Arguments. This string is changing from
“Windows.Networking.Proximity:ProximityStreamSocket” to
“Windows.Networking.Proximity:StreamSocket”
Windows.Networking.Sockets
Windows.Networking.Sockets property name changes
Brief description:
A number of properties on the Windows.Networking.Sockets changed for improved readability
Languages <JavaScript, C++, .NET>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —109
May 31, 2012
© 2012 Microsoft. All rights reserved.
Issue and details If you use the Windows.Networking.Socket APIs,
you must update your code to the following new
names.
DatagramSocketInformation
If you use DatagramSocketInformation you will need to update your code to the new names in the table below.
Previous Name New Name
DatagramSocketInformation.LocalHostName DatagramSocketInformation.LocalAddress
DatagramSocketInformation.LocalServiceName DatagramSocketInformation.LocalPort
DatagramSocketInformation.RemoteHostName DatagramSocketInformation.RemoteAddress
DatagramSocketInformation.RemoteServiceName DatagramSocketInformation.RemotePort
DatagramSocketMessageReceivedEventArgs
If you use DatagramSocketMessageReceivedEventArgs you will need to update your code to the new names in
the table below.
Previous Name New Name
DatagramSocketMessageReceivedEventArgs.
LocalHostName
DatagramSocketMessageReceivedEventArgs.
LocalAddress
DatagramSocketMessageReceivedEventArgs.
RemoteHostName
DatagramSocketMessageReceivedEventArgs.
RemoteAddress
DatagramSocketMessageReceivedEventArgs.
RemoteServiceName
DatagramSocketMessageReceivedEventArgs.
RemotePort
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —110
May 31, 2012
© 2012 Microsoft. All rights reserved.
HostName
If you use HostName.NetworkAdapter, you will need to update your code to the new name.
Previous Name New Name
HostName.NetworkAdapter HostName.IPInformation.NetworkAdapter
MessageWebSocketInformation.BandwidthStatistics
If you use MessageWebSocketInformation.BandwidthStatistics you will need to update your code to the new
names in the table below.
Previous Name New Name
BandwidthStatistics.InboundInstability BandwidthStatistics.InboundBitsPerSecondInstability
BandwidthStatistics.OutboundInstability BandwidthStatistics.OutboundBitsPerSecondInstability
StreamSocketInformation
If you use StreamSocketInformation, you will need to update your code to the new names in the table below.
Previous Name New Name
StreamSocketInformation.LocalHostName StreamSocketInformation.LocalAddress
StreamSocketInformation.LocalServiceName StreamSocketInformation.LocalPort
StreamSocketInformation.RemoteHostName StreamSocketInformation.RemoteAddress
StreamSocketInformation.RemoteServiceName StreamSocketInformation.RemotePort
StreamSocketInformation.sslStrength StreamSocketInformation.ProtectionLevel
StreamSocketInformation.SessionKey
Note: The RemoteHostName and RemoteService APIs still exist in the namespace, but their behavior has
changed. Previously, they were the resolved address and port, now they are the original data as set.
StreamSocketInformation.BandwidthStatistics
If you use StreamSocketInformation.BandwidthStatistics you will need to update your code to the new names in
the table below.
Previous Name New Name
BandwidthStatistics.InboundInstability BandwidthStatistics.InboundBitsPerSecondInstability
BandwidthStatistics.OutboundInstability BandwidthStatistics.OutboundBitsPerSecondInstability
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —111
May 31, 2012
© 2012 Microsoft. All rights reserved.
StreamSocketListenerInformation
If you use StreamSocketListenerInformation, you will need to update your code to the new name in the table
below.
Previous Name New Name
StreamSocketListenerInformation.LocalServiceName StreamSocketListenerInformation.LocalPort
StreamWebSocketInformation
If you use StreamWebSocketInformation you will need to update your code to the new names in the table
below.
Previous Name New Name
WebSocketInformation.LocalHostName WebSocketInformation.LocalAddress
StreamWebSocketInformation.BandwidthStatistics
If you use StreamWebSocketInformation.BandwidthStatistics you will need to update your code to the new
names in the table below.
Previous Name New Name
BandwidthStatistics.InboundInstability BandwidthStatistics.InboundBitsPerSecondInstability
BandwidthStatistics.OutboundInstability BandwidthStatistics.OutboundBitsPerSecondInstability
Windows.security.authentication.OnlineId
Moving to IIterable and removal of caption from API
Languages All
Changes:
1. Caption/HeaderText is being removed from the API so partners cannot specify a string in the UX.
This is because of issues with concatenation and localization.
2. OnlineIdServiceTicketRequests is now made IIterable instead of IVectorView. It is easier for
developers to implement and follows the patterns other Windows Runtime namespaces do
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —112
May 31, 2012
© 2012 Microsoft. All rights reserved.
Who is impacted?
1. The change to IIterable from IVectorView affects only partners who use native C++
2. The change to no longer support headerText/Caption affects all developers who pass a caption or
headerText and should no longer be passed.
Samples:
C++ samples
ComPtr<IVectorView<OnlineIdServiceTicketRequest*>> spTargetsView; No longer needed
MX_CHK(hr = spTargets->GetView(&spTargetsView)); No longer needed
MX_CHK(hr = spAuthRequest->AuthenticateUserAsyncAdvanced(
spTargetsView.Get(), This must be changed to spTargets.Get(),
nullptr HeaderText/Caption is no longer supported, delete this.
(CredentialPromptType)dwCredPromptOption,
&spAuthOperation));
Windows.Storage
Default collision option change for file create in StorageFolder and DownloadsFolder
Languages JavaScript, C++, .NET
Changes:
The current default behavior of the following APIs in case of a file/folder name collision is to generate unique
name (NameCollisionOption.GenerateUniqueName):
CreateFileAsync
CreateFolderAsync
RenameAsync
CopyAsync
MoveAsync
This default behavior changed to return a failure in case of name collision
(NameCollisionOption.FailIfExists)
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —113
May 31, 2012
© 2012 Microsoft. All rights reserved.
Who is impacted?
Anybody who is using any of the following APIs will be impacted since the default behavior is different now:
CreateFileAsync
CreateFolderAsync
RenameAsync
CopyAsync
MoveAsync
If you intended any of these APIs to fail in case of name collision, no change is needed in your code. But if you
intended these to succeed in case of a name collision, you will now have to pass
NameCollisionOption.GenerateUniqueName explicitly as an option.
Samples
C# Samples
Before: StorageFile file = await localFolder.CreateFileAsync(“file.txt”); // This used to succeed even if “file.txt” exist in the folder, and results in “File(1).txt” getting created. Now: StorageFile file = await localFolder.CreateFileAsync(“file.txt”); // This will throw an exception if “file.txt” exists in the local folder. So in order to get the old behavior, you would have to change your code to: StorageFile file = await localFolder.CreateFileAsync(“file.txt”, CreateCollisionOption.GenerateUniqueName); Or if you want the APIs to fail in case of collision, you should handle the exception.
Transacted streams and CreateFileAsync options
Languages JavaScript, C++, .NET
Changes:
1. Default file open behavior changes from Transacted to Non-transacted (fileAccessMode.eadWrite).
2. Transacted streams are now separated into a new runtime class StorageStreamTransaction. Commit
semantics of transacted streams are getting decoupled from FlushAsync to a new method
CommitAsync in StorageStreamTransaction.
3. As a result, the following options are getting removed from CreateFileAsync to simplify the interfaces:
var fileAccessMode = {
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —114
May 31, 2012
© 2012 Microsoft. All rights reserved.
read : 0,
readWrite: 1,
readWriteUnsafe : 2,
readWriteNoCopyOnWrite: 3
}
4. FlushAsync is now no longer needed for transacted commits, and additionally is generally not needed for
non-transacted streams either as it has a performance impact since it makes the write durable on disk.
Who is impacted?
1. Anybody who is using ReadWriteInPlace (old name: ReadWriteUnsafe) or ReadWriteNoCopyOnWrite is
immediately impacted because the values no longer exist. ReadWriteInPlace (ReadWriteUnsafe) callers
will be changed directly to ReadWrite with no impact and we will make all these changes.
ReadWriteNoCopyOnWrite uses have various possibilities:
Caller just wanted an empty write stream. This can be accomplished with OpenAsync(ReadWrite) +
put_Size(0) and is the assumption we’re making when making changes, it should be reviewed by
feature owners to see if they want the next case below.
Caller wanted empty write stream plus transactions. This can be accomplished with
OpenTransactedAsync(ReadWrite) + put_Size(0), this is currently applied only to some internal
callers.
Caller wanted empty write stream plus a separate simultaneous read stream. This was a confusing use
case and is part of why we’re getting rid of it, this can be accomplished instead with an
intermediate in-memory stream and stream copy.
Existing ReadWrite cases have similar scenarios:
Caller just wanted a writable stream. By doing nothing they still get a writable stream, but the call to
FlushAsync that was previously necessary is now no longer necessary. This is the default state most
callers will be in and they will be unchanged with the check-in, but they should review to see if
they need to remove FlushAsync or use transactions.
Caller wanted transactions. Caller will have to update to use OpenTransactedAsync.
2. All file opens will now be non-transacted by default. Please review your usage and if you intended to
have transacted writes for your scenario, please make the changes as indicated in the attached
document.
3. CLR – we are in contact with CLR team to absorb the changes.
Samples
C# Samples
// Save the current session state static async public Task SaveAsync() { var localFolder = ApplicationData.Current.LocalFolder; // Get the output stream for the SessionState file.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —115
May 31, 2012
© 2012 Microsoft. All rights reserved.
StorageFile file = await localFolder.CreateFileAsync(filename, CreationCollisionOption.ReplaceExisting); StorageStreamTransaction transaction = await file.OpenTransactedAsync(); IRandomAccessStream raStream = transaction.Stream; // Serialize the Session State. DataContractSerializer serializer = new DataContractSerializer(typeof(Dictionary<string, object>), knownTypes_); serializer.WriteObject(raStream.AsStreamForWrite(), sessionState_); await transaction.CommitAsync (); transaction.Close(); }
JavaScript Samples
writeText: function (fileName, str) { var that = this; return that.folder.createFileAsync(fileName, sto.CreationCollisionOption.replaceExisting).then(function (fileItem) { return fileItem.openTransactedAsync(); }).then(function (transaction) { var writer = new Windows.Storage.Streams.DataWriter(transaction.stream); var count = writer.writeString(str); return writer.storeAsync().then(function() { return transaction.commitAsync ().then(function() { transaction.close(); return count; }); }); }); }
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —116
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.Storage.ApplicationData
Changes to IApplicationData::SetVersionAsync exception handling
Brief description:
Throwing exceptions in SetVersionAsync will terminate the process.
Languages JavaScript, C++, .NET
Issue and details IApplicationData::SetVersionAsync is being changed so that
exceptions thrown in the caller-provided callback will terminate the
process.
This is in alignment with similar breaking changes for exceptions
during async calls.
Prior to this change, SetVersionAsync had depended on the callback
to throw an exception as a means of canceling the pending version-
change. This is not a desired design pattern, and doesn’t work well
when the callback defers completion of the operation.
Samples usage or steps to take to
migrate code
Do not throw exceptions back to the
IApplicationData::SetVersionAsync call
Removal of IApplicationData::get_RoamingStorageUsage()
Brief description:
The get_RoamingStorageUsage() method has been removed.
Languages JavaScript, C++, .NET
Issue and details IApplicationData::get_RoamingStorageUsage() has been removed.
Samples usage or steps to take to
migrate code
Remove calls to IApplicationData::get_RoamingStorageUsage().
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —117
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.Storage.Streams
DataReader::DetachStream and DataWriter::DetachStream will fail
Brief Description:
Calling DetachStream while an async operation is in flight on the data reader or data writer will result in failure
– the stream will not be detached.
Languages C++, C#, Visual Basic
Issue Previously when calling DetachStream method on a data reader or data writer, it
will yield a stream that may still be in use by the underlying data reader or data
writer if an asynchronous operation is still outstanding. The results of this will be
unpredictable – calls on the returned stream may fail, the stream may have
discontinuities, etc…
With this change, the call will now fail in this case therefore providing predictable
experience.
Mitigation or Migration
processes
If a call to DetachStream on a data reader or data writer fails with an invalid
ERROR_INVALID_OPERATION)), ensure that no asynchronous operations are
outstanding when calling DetachStream. If necessary, move the detach to after
completion handling of the outstanding asynchronous operations.operation
code (HRESULT_FROM_WIN32(
Windows.System
New restrictions on the protocols that Metro style apps can launch and register for
Brief description:
To increase end-user confidence in their Metro style apps additional restrictions have been put in place on what
protocol schemes an app can launch and register for.
Languages JavaScript
Issue and details In the Consumer Preview the Windows.System.Launcher API allowed an app to
launch any type of protocol. This enables apps to launch protocols like http:,
mailto:, feed:, etc., which in turns enables legitimate end-user scenarios. However
it also means that apps can launch protocols like telnet, and ierss,, which do not
have legitimate scenarios in a Metro style app. Allowing apps to launch these
unneeded protocols opens up additional attack surface in the platform.
For Windows 8 Release Preview, apps are blocked from launching any protocol
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —118
May 31, 2012
© 2012 Microsoft. All rights reserved.
scheme that is handled by an OS component that does not provide a legitimate
scenario for a Metro style app. This change reduces the potential attack surface
that malicious Metro style apps can target in Windows 8. The full list of blocked
protocol schemes is listed below. These protocols are only blocked when they
are handled by an OS component or a desktop app.
Protocol Scheme
Explorer.AssocActionId.BurnSelection
Explorer.AssocActionId.CloseSession
Explorer.AssocActionId.EraseDisc
Explorer.AssocActionId.ZipSelection
Explorer.AssocProtocol.search-ms
Explorer.BurnSelection
Explorer.CloseSession
Explorer.EraseDisc
Explorer.ZipSelection
iehistory
ierss
LDAP
res
rlogin
StickyNotes
telnet
tn3270
windowsmediacenterapp
windowsmediacenterssl
windowsmediacenterweb
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —119
May 31, 2012
© 2012 Microsoft. All rights reserved.
WMP11.AssocProtocol.MMS
In addition to blocking the launch of certain protocols for Metro style apps there
are also a few additional protocols that Metro style apps will not be allowed to
register for. These protocols are used internally by Explorer and should not be
taken over by an app.
Explorer.AssocActionId.BurnSelection
Explorer.AssocActionId.CloseSession
Explorer.AssocActionId.EraseDisc
Explorer.AssocActionId.ZipSelection
Explorer.AssocProtocol.search-ms
Explorer.BurnSelection
Explorer.CloseSession
Explorer.EraseDisc
Explorer.ZipSelection
Samples usage or
steps to take to
migrate code
No apps should use these protocols so in general no action needs to be taken. If
an app is using these protocols then they must reevaluate their scenario to see if
it fits the Metro style app model. If so they will need to use Windows Runtime
APIs and other platform tools to achieve the scenario.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —120
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.System.UserProfile.UserInformation
Converted getting user names to asynchronous methods
Languages JavaScript, C++, .NET
Changes:
Retrieving the user names can involve retrieval of information from the network, and can therefore be slow.
Apps should not hang as a result of this latency, so the retrieval has been updated to be asynchronous. Hence
we converted the retrieval of user name properties from synchronous to asynchronous methods:
Removed DisplayName property and replaced it with the method GetDisplayNameAsync
Removed FirstName property and replaced it with the method GetFirstNameAsync
Removed LastName property and replaced it with the method GetLastNameAsync
Who is impacted?
Anyone using the following properties from the UserInformation object:
DisplayName
FirstName
LastName
Samples
C# Samples
Before: string displayName = Windows.System.UserProfile.UserInformation.DisplayName; string firstName = Windows.System.UserProfile.UserInformation.FirstName; string lastName = Windows.System.UserProfile.UserInformation.LastName; Now: string displayName = await Windows.System.UserProfile.UserInformation.GetDisplayNameAsync(); string firstName = await Windows.System.UserProfile.UserInformation.GetFirstNameAsync(); string lastName = await Windows.System.UserProfile.UserInformation.GetLastNameAsync();
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —121
May 31, 2012
© 2012 Microsoft. All rights reserved.
JavaScript Samples
Before: var displayName = Windows.System.UserProfile.UserInformation.displayName; var firstName = Windows.System.UserProfile.UserInformation.displayName; var lastName = Windows.System.UserProfile.UserInformation.displayName; Now: Windows.System.UserProfile.UserInformation.getDisplayNameAsync().done(function (result) { if (result) { // result is the Display Name } }); Windows.System.UserProfile.UserInformation.getFirstNameAsync().done(function (result) { if (result) { // result is the First Name } }); Windows.System.UserProfile.UserInformation.getLastNameAsync().done(function (result) { if (result) { // result is the Last Name } });
Windows.UI.Core.CoreWindow
Close method now fails when called on main window
Languages C++, C#, Visual Basic
Issue This change will cause calls to CoreWindow::Close to fail for the main
window of an app.
Mitigation or
Migration processes
Symptoms Resolution
CoreWindow::Close returns E_ILLEGAL_METHOD_CALL
In the unlikely event this behavior is necessary, call CoreApplication::Exit instead
ICoreWindowPopupShowingEventArgs
Languages C++
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —122
May 31, 2012
© 2012 Microsoft. All rights reserved.
Changes:
1. New ICoreWindowPopupShowingEventArgs interface created, with a TrySetSize method.
2. This event args is passed to the ICoreWindowDialog and ICoreWindowFlyout Showing event handler so
that the client can set the size of the CoreWindow from the Showing event handler:
[eventadd] HRESULT Showing([in] Windows.Foundation.TypedEventHandler
<Windows.UI.Core.CoreWindow *,
Windows.UI.Core.CoreWindowPopupShowingEventArgs *> *handler,
[out, retval] EventRegistrationToken *cookie);
3. There is a new runtime class CoreWindowPopupShowingEventArgs.
4. This change removes the need for clients to get the CoreWindow’s hwnd and to call SetWindowPos on it
to set its size. (This method will not be possible with some other upcoming changes.)
Who is impacted?
1. Any user of CoreWindowDialog and CoreWindowFlyout will need to change their code to pass the new
event args down to their Showing event.
2. They will also need to call TrySetSize instead of SetWindowPos.
Samples:
C++ Samples
auto agileCallback = Callback<Implements<RuntimeClassFlags<ClassicCom>, ITypedEventHandler<CoreWindow*, CoreWindowPopupShowingEventArgs *>, FtmBase>>([](ICoreWindow *pCoreWindow, ICoreWindowPopupShowingEventArgs *pShowingEventArgs) -> HRESULT { HWND hwndContent = nullptr; HRESULT hr = IUnknown_GetWindow(pCoreWindow, &hwndContent); if (SUCCEEDED(hr)) { DWORD dwDeferCookie = 0; hr = CoreWindowHostedHWNDElement::Create(hwndContent, EC_MultiTouch | EC_PreserveAlphaChannel, nullptr, &dwDeferCookie, &g_peHostedInCoreWindow); if (SUCCEEDED(hr)) { ValueRef vrSize; const SIZE *pcSize = g_peHostedInCoreWindow->GetExtent(&vrSize); // (Or some other way to get the preferred size) Windows::Foundation::Size size; size.Width = pcSize->cx; size.Height = pcSize->cy; Windows::Foundation::Size sizeRes; pShowingEventArgs->TrySetSize(size, &sizeRes); g_peHostedInCoreWindow->SetWidth(sizeRes.Width); g_peHostedInCoreWindow->SetHeight(sizeRes.Height); g_peHostedInCoreWindow->SetVisible(true); g_peHostedInCoreWindow->EndDefer(dwDeferCookie); } }
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —123
May 31, 2012
© 2012 Microsoft. All rights reserved.
if (FAILED(hr)) { pCoreWindow->Close(); } return hr; }); hr = agileCallback ? S_OK : E_OUTOFMEMORY; if (SUCCEEDED(hr)) { EventRegistrationToken cookie; // bug, registration leaked hr = spCoreWindowDialog->add_Showing(agileCallback.Get(), &cookie); ... }
Deprecation of Invoke and InvokeAsync methods and addition of RunAsync
Brief description:
We are eliminating one schedule API and updating a second one so that CoreWindows dispatcher functionality
is in line with Windows Runtime guidelines for Async processing.
Languages C++
Issue and details The CoreWindow Invoke API is a blocking all, and the InvokeAsync API, while not
blocking, does not use the Windows Runtime Async pattern. We are eliminating
the Invoke API to improve the reliability of Windows and Windows apps (by
removing code paths that can lead to deadlocks), and we have replaced
InvokeAsync with RunAsync, a new API that has Windows Runtime Async support.
Samples usage or steps to
take to migrate code
Apps should use the new RunAsync method to schedule callbacks on the window
thread. Callers can use the returned IAsyncAction object to set a completion
routine to get the completion status.
If the app does not need to know about the completion of the callback then they
do not have to set the callback and ignore returned IAsyncAction object
IInternalCoreWindow interface moved to private
Brief description:
An interface used for communication between shell and CoreWindow was incorrectly marked as public and has
been made private.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —124
May 31, 2012
© 2012 Microsoft. All rights reserved.
Languages C++
Issue and details The IInternalCoreWindow interface is an internal interface used so that events
associated with Win32 Window Messages can be forwarded from CoreWindow to
other Windows Runtime objects that raise Windows Runtime events.
Samples usage or steps to
take to migrate code
The interface is no longer available to app developers. In general, developers
interested in events such as theme changes have Windows Runtime access to
these events through other Windows Runtime objects. (In one case,
ViewStateChanged, that event has been deprecated in favor of resize events.)
Method calls on a proxy CoreWindow will fail even if the object is smuggled back to the
UI thread
Brief description:
We are returning an error in a scenario where we used to return success (but with invalid data); the scenario is
one that does not and cannot work, so we are now letting the app know there is a problem here.
Languages C++
Issue and details When an app using CoreWindow is doing processing on a non UI thread, the
CoreWindow object is a proxy object, and the CoreWindow API infrastructure
does not maintain state properties such as foreground status on the proxy object.
There is code in CoreWindow to check that these properties are only called on
the right (UI) thread, but those checks are bypassed if the developer uses the new
RunAsync CoreDispatcher API. In that scenario, the UI thread does the
processing, bypassing the checks, but returns invalid data (since the state in
question is not maintained on the proxy object.)
We are treating this as a breaking change, but note that the only scenarios it will
break are scenarios that already do not work properly.
Samples usage or steps to
take to migrate code
If this change breaks app code, it is only serving notice that the method call has
been returning invalid data. An app that hits this breaking change needs to make
method calls on the real core window object, not on a proxy.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —125
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.UI.Input
Additional API support for mouse button transitions in IPointerPointProperties
Brief description:
PointerPointProperties for mouse input now provides a) the state of the X1 and X2 mouse buttons as well as b)
the button state change (if any) associated with the pointer event.
Languages C++, .NET
Issue and details IPointerPointProperties provides two new properties:
[propget] HRESULT IsX1ButtonPressed([out, retval] boolean *value)
[propget] HRESULT IsX2ButtonPressed([out, retval] boolean *value)
These can be used to get the state of the X1 and X2 buttons.
In addition, another new property:
[propget] HRESULT PointerUpdateKind([out, retval] PointerUpdateKind
*value);
can be used to find out if any mouse button has changed state as part of this
event. PointerUpdateKind has these values:
typedef enum PointerButtonChange {
None = 0,
LeftButtonDown,
LeftButtonUp,
RightButtonDown,
RightButtonUp,
MiddleButtonDown,
MiddleButtonUp,
X1ButtonDown,
X1ButtonUp,
X2ButtonDown,
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —126
May 31, 2012
© 2012 Microsoft. All rights reserved.
X2ButtonUp,
} PointerButtonChange;
Samples usage or steps to
take to migrate code
No changes are required to migrate code. However, prior to this change, apps
that wanted to take action on button state changes were required to track button
state on each pointer event and compare them to detect differences. The new
PointerButtonChange property makes this much simpler, and developers should
consider moving to use this property.
Changes in swipe and translation deltas
Brief description:
Gesture recognition uses a distance threshold to distinguish taps from drags. By default, we now remove that
distance from some drag-based gestures in order to minimize a perceived “jump” at the start of the interaction.
Developers can opt-into the old behavior and get exact manipulations if they choose to do so.
Languages JavaScript, C++, .NET
Issue and details The issue:
When using the GestureRecognizer or InteractionContext for pan or swipe interactions, a
small but noticeable jump occurs when the manipulation begins.
The change:
To remove this “jump” when we determine it is a drag-based gesture and being sending
gesture updates, we changed the default behavior of the GestureRecognizer and
InteractionContext to no longer include the “tap threshold” distance in the initial update.
This will occur in the following manipulations:
1. Pan (all directions)
2. Cross-slide (both horizontal and vertical)
Samples usage
or steps to take
to migrate code
No code changes are needed to use the new default behavior. If you wish to retain the
prior behavior (in which deltas include the tap threshold, yet have the jump behavior
described above) you can do so with GestureRecognizer flags or by setting
InteractionContext configuration flags.
Gesture recognizer flags (using C++)
Windows::UI::Input::GestureRecognizer^ gestureRecognizer;
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —127
May 31, 2012
© 2012 Microsoft. All rights reserved.
gestureRecognizer->ManipulationExact = true;
gestureRecognizer->CrossSlideExact = true;
Interaction Context configuration flags:
INTERACTION_CONTEXT_CONFIGURATION cfg[] =
{
{
INTERACTION_ID_MANIPULATION,
INTERACTION_CONFIGURATION_FLAG_MANIPULATION |
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_EXACT | // Preserve
initial jump at manipulation start
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_TRANSLATION_X |
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_TRANSLATION_Y |
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_ROTATION |
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_SCALING |
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_TRANSLATION_INERTIA
|
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_ROTATION_INERTIA |
INTERACTION_CONFIGURATION_FLAG_MANIPULATION_SCALING_INERTIA
},
{
INTERACTION_ID_CROSS_SLIDE,
INTERACTION_CONFIGURATION_FLAG_CROSS_SLIDE |
INTERACTION_CONFIGURATION_FLAG_CROSS_SLIDE_EXACT | // Preserve
initial jump at cross slide start
INTERACTION_CONFIGURATION_FLAG_CROSS_SLIDE_SELECT |
INTERACTION_CONFIGURATION_FLAG_CROSS_SLIDE_SPEED_BUMP |
INTERACTION_CONFIGURATION_FLAG_CROSS_SLIDE_REARRANGE
}
};
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —128
May 31, 2012
© 2012 Microsoft. All rights reserved.
hr = SetInteractionConfigurationInteractionContext(
m_hInteractionContext,
ARRAYSIZE(cfg),
cfg);
>
Windows.UI.Input.Inking
Ink API will now return a vector of runtime classes instead of a vector of appropriate
interfaces
Brief description:
Returning a vector of runtime classes instead of a vector of appropriate interfaces – which means that four of
Windows.UI.Input.Inking.* collection of interfaces are becoming collection of runtime classes
Languages C++, C#, ABI
Issue and details 1. At the moment ISVs need to use (e.g.) both InkStroke and IInkStroke
(the second is used when dealing with collections). This introduces
unnecessary noise and may confuse ISV community. with this
change we are exposing only runtime classes (interfaces need not
be used at all).
2. Marshaling annotations are not supported for interfaces, and hence
in C++ binding all four affected interfaces are annotated as
‘standard’ and not as ‘none’ (appropriate runtime classes are
annotated as ‘none’). this is how the issue was discovered. we are
solve this problem by returning runtime classes instead.
Samples usage or steps to take to
migrate code
previous (green highlighted letter ‘I’):
interface IVector<IInkStrokeRenderingSegment *>;
interface IVector<IInkStroke *>;
interface IVector<IInkRecognizer *>;
interface IVector<IInkRecognitionResult *>;
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —129
May 31, 2012
© 2012 Microsoft. All rights reserved.
now:
interface IVector<InkStrokeRenderingSegment *>;
interface IVector<InkStroke *>;
interface IVector<InkRecognizer *>;
interface IVector<InkRecognitionResult *>;
Windows.UI.Notifications
Query strings for tile/toast notifications not appended by default
Languages: JavaScript, C++, .NET
Brief description:
In the original Consumer Preview, including images that start with http:// or https:// in the notification
payload for tile and toast notifications are automatically appended with query strings that denote the scale,
contrast, and language of the client PC.
For example:
Notification xml contains: www.website.com/images/hello.png
On Consumer Preview builds, Windows attempts to download:
www.website.com/images/hello.png?scale=100&contrast=standard&lang=en-us
After Consumer Preview, query strings will no longer be appended by default to the image URL. An optional
attribute will need to be added to the payload in order for Windows to append query strings to the image URL.
In order to opt in for Windows to append the query string to the web image URLs, the optional Boolean
attribute addImageQuery needs to be added to the visual, binding, or image element in the xml payload.
Additionally, the parameters have been changed to be Microsoft specific:
Old New
scale ms-scale
contrast ms-contrast
lang ms-lang
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —130
May 31, 2012
© 2012 Microsoft. All rights reserved.
For example, by default, Windows attempts to download www.website.com/images/hello.png .
If you opt-in to query strings, Windows attempts to download www.website.com/images/hello.png?ms-
scale=100&ms-contrast=standard&ms-lang=en-us.
Who is impacted?
This will affect owners of web servers who host images that are used by tile or toast notifications AND using the
query strings. If your web server was depending on the query string parameters to be present to construct an
image, you will need to either :
1. Update your web server to not depend on those images.
—or—
2. Update your web server to use the renamed parameters and update your notification sending code to
include the new optional attribute addImageQuery.
Samples:
All of these examples opt-in to query strings and are valid:
<tile> <visual addImageQuery="true"> <binding template="TileWideImageAndText01"> <image id="1" src="www.website.com/images/hello.png"/> <text id="1">Hello World!</text> </binding> </visual> </tile>
<tile> <visual> <binding addImageQuery="true" template="TileWideImageAndText01"> <image id="1" src="www.website.com/images/hello.png"/> <text id="1">Hello World!</text> </binding> </visual> </tile>
<tile> <visual> <binding template="TileWideImageAndText01"> <image addImageQuery="true" id="1" src="www.website.com/images/hello.png"/> <text id="1">Hello World!</text> </binding> </visual> </tile>
<tile> <visual> <binding template="TileWidePeekImage05"> <image addImageQuery="true" id="1" src="www.website.com/images/hello.png"/>
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —131
May 31, 2012
© 2012 Microsoft. All rights reserved.
<image id="2" src="www.website.com/images/hello.png"/> <text id="1">Hello World!</text> <text id="2">Hello World again!</text> </binding> </visual> </tile>
Windows.UI.ViewManagement
ViewStateChanged event removed
Languages: JavaScript, C++, .NET
Changes:
ViewStateChanged event was removed from the API surface. To know when view state has changed for
your app, please register for the window resize event, and query for the view state in the resize
handler.
The pattern of using the window resize event already works in the Consumer Preview. You don’t need
to wait for the Release Preview to respond to this change. We recommend apps move over to the
recommended pattern (outlined below) as soon as possible.
Note Window resize will always fire whenever view state changes.
Who is impacted?
All apps that currently listen for and handle ViewStateChanged event.
Samples:
JavaScript Samples
Previously, your app would do something like this to handle view state changes:
// Register for the viewstatechanged event
var appView = Windows.UI.ViewManagement.ApplicationView;
appView.getForCurrentView().addEventListener("viewstatechanged", onViewStateChanged);
...
function onViewStateChanged(eventArgs) {
// Obtain view state from the event payload
var myViewState = eventArgs.viewState;
}
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —132
May 31, 2012
© 2012 Microsoft. All rights reserved.
Now apps should do this:
// Register for the window resize event
window.addEventListener("resize", onResize);
...
function onResize() {
// Obtain view state by explicitly querying for it
var myViewState = Windows.UI.ViewManagement.ApplicationView.value;
}
C# Samples
Previously, your app would do something like this to handle view state changes:
using Windows.UI.ViewManagement;
...
// Register for the viewstatechanged event
ApplicationView.GetForCurrentView().ViewStateChanged += ViewStateChanged;
...
private void ViewStateChanged(ApplicationView sender, ApplicationViewStateChangedEventArgs e)
{
// Obtain view state from event payload
ApplicationViewState myViewState = e.ViewState;
}
Now apps should do this:
using Windows.UI.ViewManagement;
...
// Register for the window resize event
Window.Current.SizeChanged += WindowSizeChanged;
...
private void WindowSizeChanged(object sender, Windows.UI.Core.WindowSizeChangedEventArgs e)
{
// Obtain view state by explicitly querying for it
ApplicationViewState myViewState = ApplicationView.Value;
}
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —133
May 31, 2012
© 2012 Microsoft. All rights reserved.
Windows.Web.Syndication
Windows.Web.Syndication property name changes
Brief description:
A number of properties of Windows.Web.Syndication changed for improved readability
Languages C++, .NET
Issue and details If you use the Windows.Web.Syndication APIs,
you must update your code to the following new
names.
This does not impact JavaScript, since the language
binding will camel case the names.
RetrievalProgress
If you used RetrievalProgress you will need to update your code to the new name.
Previous Name New Name
RetrievalProgress. bytesRetrieved RetrievalProgress.BytesRetrieved
RetrievalProgress. totalBytesToRetrieve RetrievalProgress. TotalBytesToRetrieve
TransferProgress. bytesRetrieved TransferProgress.BytesRetrieved
TransferProgress. totalBytesToRetrieve TransferProgress. TotalBytesToRetrieve
TransferProgress. bytesSent TransferProgress. BytesSent
TransferProgress. totalBytesToSend TransferProgress. TotalBytesToSend
Remove ToString method from ISyndicationText
Brief description:
We have removed the ISyndicationText::ToString method. The Windows Runtime does not support methods
named ToString.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —134
May 31, 2012
© 2012 Microsoft. All rights reserved.
Languages <JavaScript, C++, .NET>
Issue and details The ToString method in SyndicationText and
SyndicationContent has been removed.
XHTML content can be retrieved as a string using
the Text property. If an app needs to manipulate
XHTML content as XML, the Xml property is
available.
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —135
May 31, 2012
© 2012 Microsoft. All rights reserved.
Appendix: Summary of API name changes
Area Current Value New Value
AppBar AppBarFillBrush AppBarBackgroundThemeBrush
AppBar AppBarItemBackgroundBrush AppBarItemBackgroundThemeBrush
AppBar AppBarItemDisabledForegroundBru
sh
AppBarItemDisabledForegroundThemeBrush
AppBar AppBarItemForegroundBrush AppBarItemForegroundThemeBrush
AppBar AppBarItemHoverBackgroundBrush AppBarItemPointerOverBackgroundThemeBrush
AppBar AppBarItemHoverForegroundBrush AppBarItemPointerOverForegroundThemeBrush
AppBar AppBarItemPressedForegroundBrus
h
AppBarItemPressedForegroundThemeBrush
Application ApplicationHoverTextBrush ApplicationPointerOverForegroundThemeBrush
Application ApplicationPageBackgroundBrush ApplicationPageBackgroundThemeBrush
Application ApplicationPressedTextBrush ApplicationPressedForegroundThemeBrush
Application ApplicationSecondaryTextBrush ApplicationSecondaryForegroundThemeBrush
Application ApplicationTextBrush ApplicationForegroundThemeBrush
BackButton BackButtonBackgroundBrush BackButtonBackgroundThemeBrush
BackButton BackButtonDisabledGlyphBrush BackButtonDisabledForegroundThemeBrush
BackButton BackButtonGlyphBrush BackButtonForegroundThemeBrush
BackButton BackButtonHoverBackgroundBrush BackButtonPointerOverBackgroundThemeBrush
BackButton BackButtonHoverGlyphBrush BackButtonPointerOverForegroundThemeBrush
BackButton BackButtonPressedGlyphBrush BackButtonPressedForegroundThemeBrush
Button ButtonBackgroundBrush ButtonBackgroundThemeBrush
ComboBox ComboBoxDisabledBorderBrush ComboBoxDisabledBorderThemeBrush
ComboBox ComboBoxFocusedTextBrush ComboBoxFocusedForegroundThemeBrush
ComboBox ComboBoxHighlightBackgroundBrus
h
ComboBoxFocusedBackgroundThemeBrush
ComboBox ComboBoxHighlightFillBrush ComboBoxSelectedBackgroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —136
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
ComboBox ComboBoxHighlightHoverFillBrush ComboBoxSelectedPointerOverBackgroundThemeBrush
ComboBoxItem ComboBoxItemHighlightFillBrush !!!!Split into two
ComboBoxItem ComboBoxItemSelectedBackgroundThemeBrush
ComboBoxItem ComboBoxItemSelectedForegroundThemeBrush
ComboBoxItem ComboBoxItemHighlightHoverFillBr
ush
ComboBoxItemSelectedPointerOverBackgroundThemeBru
sh
ComboBoxItem ComboBoxItemPointerOverFillBrush ComboBoxItemPointerOverBackgroundThemeBrush
ComboBoxItem ComboBoxItemPressedFillBrush !!!!Split into two
ComboBoxItem ComboBoxItemPressedBackgroundThemeBrush
ComboBoxItem ComboBoxItemPressedForegroundThemeBrush
ComboBox ComboBoxNormalBackgroundBrush ComboBoxBackgroundThemeBrush
ComboBox ComboBoxNormalBorderBrush ComboBoxBorderThemeBrush
ComboBox ComboBoxPointerOverBorderBrush ComboBoxPointerOverBorderThemeBrush
ComboBox ComboBoxPointerOverFillBrush ComboBoxPointerOverBackgroundThemeBrush
ComboBox ComboBoxPopupBackgroundBrush ComboBoxPopupBackgroundThemeBrush
ComboBox ComboBoxPopupBorderBrush ComboBoxPopupBorderThemeBrush
ComboBox ComboBoxPopupTextBrush ComboBoxPopupForegroundThemeBrush
ComboBox ComboBoxPressedBorderBrush ComboBoxPressedBorderThemeBrush
ComboBox ComboBoxPressedFillBrush ComboBoxPressedBackgroundThemeBrush
ComboBox ComboBoxPressedTextBrush ComboBoxPressedForegroundThemeBrush
Control ControlBorderBrush cut (not used)
Control ControlDisabledBrush !!!!DELETE and replace with:
Button ButtonDisabledBorderThemeBrush
RepeatButton RepeatButtonDisabledBorderThemeBrush
Control ControlDisabledFillBrush !!!!DELETE and replace with:
Button ButtonDisabledBackgroundThemeBrush
RepeatButton RepeatButtonDisabledBackgroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —137
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
ComboBox ComboBoxDisabledBackgroundThemeBrush
Control ControlDisabledTextBrush !!!!DELETE and replace with:
Button ButtonDisabledForegroundThemeBrush
RepeatButton RepeatButtonDisabledForegroundThemeBrush
ToggleButton ToggleButtonDisabledForegroundThemeBrush
RadioButton RadioButtonDisabledBorderThemeBrush
RadioButton RadioButtonContentDisabledForegroundThemeBrush
CheckBox CheckBoxDisabledBorderThemeBrush
CheckBox CheckBoxContentDisabledForegroundThemeBrush
ComboBoxItem ComboBoxItemDisabledForegroundThemeBrush
ListBox ListBoxItemDisabledForegroundThemeBrush
ComboBox ComboBoxDisabledForegroundThemeBrush
ComboBox ComboBoxArrowDisabledForegroundThemeBrush
ListBox ListBoxDisabledForegroundThemeBrush
Control ControlForegroundBrush !!!!DELETE and replace with:
Button ButtonForegroundThemeBrush
Button ButtonPressedBackgroundThemeBrush
RepeatButton RepeatButtonForegroundThemeBrush
RepeatButton RepeatButtonPressedBackgroundThemeBrush
ToggleButton ToggleButtonForegroundThemeBrush
ToggleButton ToggleButtonPressedBackgroundThemeBrush
RadioButton RadioButtonContentForegroundThemeBrush
CheckBox CheckBoxContentForegroundThemeBrush
Control ControlGlyphBrush !!!!DELETE and replace with:
CheckBox CheckBoxForegroundThemeBrush
ComboBox ComboBoxArrowForegroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —138
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
Control ControlGlyphPressedBrush !!!!DELETE and replace with:
RadioButton RadioButtonPressedForegroundThemeBrush
CheckBox CheckBoxPressedForegroundThemeBrush
Control ControlHeaderBrush cut (not used)
Control ControlHighlightBrush cut (not used)
Control ControlNormalFillBrush cut (not used)
Control ControlNormalStrokeBrush !!!!DELETE and replace with:
Button ButtonBorderThemeBrush
RepeatButton RepeatButtonBorderThemeBrush
Control ControlPointerOverFillBrush !!!!DELETE and replace with:
Button ButtonPointerOverBackgroundThemeBrush
RepeatButton RepeatButtonPointerOverBackgroundThemeBrush
Control ControlPointerOverStrokeBrush cut (not used)
Control ControlPressedFillBrush cut (not used)
Control ControlPressedTextBrush !!!!DELETE and replace with:
Button ButtonPressedForegroundThemeBrush
RepeatButton RepeatButtonPressedForegroundThemeBrush
ToggleButton ToggleButtonPressedForegroundThemeBrush
Control ControlTransparentFillBrush !!!!DELETE and replace with:
HyperlinkButton HyperlinkButtonBackgroundThemeBrush
HyperlinkButton HyperlinkButtonBorderThemeBrush
TextBlock,
CCoreServices::GetDefaultT
extBrush
DefaultTextBrush DefaultTextForegroundThemeBrush
Slider DisabledTransparentOutlineBrush SliderDisabledBorderThemeBrush
FlipView FlipViewButtonBackgroundBrush FlipViewButtonBackgroundThemeBrush
FlipView FlipViewButtonBorderBrush FlipViewButtonBorderThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —139
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
FlipView FlipViewButtonPointerOverBorderBr
ush
FlipViewButtonPointerOverBorderThemeBrush
FlipView FlipViewButtonPointerOverFillBrush FlipViewButtonPointerOverBackgroundThemeBrush
FlipView FlipViewButtonPressedBorderBrush FlipViewButtonPressedBorderThemeBrush
FlipView FlipViewButtonPressedFillBrush FlipViewButtonPressedBackgroundThemeBrush
FlipView FlipViewGlyphArrowBrush FlipViewButtonForegroundThemeBrush
FlipView FlipViewGlyphArrowPointerOverBrus
h
FlipViewButtonPointerOverForegroundThemeBrush
FlipView FlipViewGlyphArrowPressedBrush FlipViewButtonPressedForegroundThemeBrush
FocusVisual FocusVisualBlackStrokeBrush FocusVisualBlackStrokeThemeBrush
FocusVisual FocusVisualWhiteStrokeBrush FocusVisualWhiteStrokeThemeBrush
HyperlinkButton HyperlinkDisabledBrush HyperlinkDisabledThemeBrush
HyperlinkButton HyperlinkPointerOverBrush HyperlinkPointerOverForegroundThemeBrush
HyperlinkButton HyperlinkPressedTextBrush HyperlinkPressedForegroundThemeBrush
HyperlinkButton HyperlinkRestColorBrush HyperlinkForegroundThemeBrush
Control InputControlDisabledFillBrush !!!!DELETE and replace with:
RadioButton RadioButtonDisabledBackgroundThemeBrush
CheckBox CheckBoxDisabledBackgroundThemeBrush
Control InputControlDisabledGlyphBrush !!!!DELETE and replace with:
RadioButton RadioButtonDisabledForegroundThemeBrush
CheckBox CheckBoxDisabledForegroundThemeBrush
Control InputControlGlyphBrush !!!!DELETE and replace with:
RadioButton RadioButtonForegroundThemeBrush
CheckBox CheckBoxForegroundThemeBrush
Control InputControlNormalFillBrush !!!!DELETE and replace with:
RadioButton RadioButtonBackgroundThemeBrush
CheckBox CheckBoxBackgroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —140
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
Control InputControlPointerOverFillBrush !!!!DELETE and replace with:
RadioButton RadioButtonPointerOverBackgroundThemeBrush
CheckBox CheckBoxPointerOverBackgroundThemeBrush
Control InputControlPointerOverStrokeBrus
h
!!!!DELETE and replace with:
RadioButton RadioButtonPointerOverBorderThemeBrush
CheckBox CheckBoxPointerOverBorderThemeBrush
Control InputControlPressedFillBrush !!!!DELETE and replace with:
RadioButton RadioButtonPressedBackgroundThemeBrush
RadioButton RadioButtonPressedBorderThemeBrush
CheckBox CheckBoxPressedBackgroundThemeBrush
CheckBox CheckBoxPressedBorderThemeBrush
Control InputControlStrokeBrush !!!!DELETE and replace with:
RadioButton RadioButtonBorderThemeBrush
CheckBox CheckBoxBorderThemeBrush
Control InputControlTextBrush !!!!DELETE and replace with:
ComboBox ComboBoxForegroundThemeBrush
ListBox ListBoxForegroundThemeBrush
ListBox ListBoxFocusFillBrush ListBoxFocusBackgroundThemeBrush
ListBox ListBoxItemHighlightFillBrush ListBoxItemSelectedBackgroundThemeBrush
ListBox **NEW** ListBoxItemSelectedForegroundThemeBrush
ListBox ListBoxItemHighlightHoverFillBrush ListBoxItemSelectedPointerOverBackgroundThemeBrush
ListBox ListBoxItemPointerOverFillBrush ListBoxItemPointerOverBackgroundThemeBrush
ListBox ListBoxItemPressedFillBrush ListBoxItemPressedBackgroundThemeBrush
ListBox ListBoxItemPressedForegroundBrush ListBoxItemPressedForegroundThemeBrush
ListBox ListBoxNormalBorderBrush ListBoxBorderThemeBrush
ListBox ListBoxNormalFillBrush ListBoxBackgroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —141
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
ListViewItem ListViewItemCheckGlyphBrush ListViewItemCheckThemeBrush
ListViewItem ListViewItemCheckHintGlyphBrush ListViewItemCheckHintThemeBrush
ListViewItem ListViewItemDragBackgroundBrush ListViewItemDragBackgroundThemeBrush
ListViewItem **NEW** ListViewItemDragForegroundThemeBrush
ListViewItem ListViewItemHighlightBrush ListViewItemSelectedBackgroundThemeBrush
ListViewItem ListViewItemKeyboardFocusBrush ListViewItemFocusBorderThemeBrush
ListViewItem ListViewItemOverlayBackgroundBrus
h
ListViewItemOverlayBackgroundThemeBrush
ListViewItem ListViewItemOverlaySecondaryTextB
rush
ListViewItemOverlaySecondaryForegroundThemeBrush
ListViewItem ListViewItemOverlayTextBrush ListViewItemOverlayForegroundThemeBrush
ListViewItem ListViewItemPlaceholderRectBrush ListViewItemPlaceholderBackgroundThemeBrush
ListViewItem ListViewItemPointerOverBrush ListViewItemPointerOverBackgroundThemeBrush
ListViewItem ListViewItemSelectedPointerOverBor
derBrush
!!!!Split into two
ListViewItem ListViewItemSelectedPointerOverBackgroundThemeBrush
ListViewItem ListViewItemSelectedPointerOverBorderThemeBrush
ListViewItem ListViewItemSelectedPointerOverBru
sh
cut
ListViewItem ListViewItemSelectingCheckmarkBru
sh
ListViewItemCheckSelectingThemeBrush
ListViewItem ListViewItemSemiTransparentHighlig
htBrush
cut
ListViewItem ListViewItemVeryTransparentHighlig
htBrush
cut
ListViewItem MediaPlayerControlPanelBrush cut
ListViewItem MediaPlayerDownloadProgressIndic
atorBrush
cut
ListViewItem MediaPlayerErrorPanelBrush cut
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —142
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
ListViewItem MediaPlayerTextBrush cut
ListViewItem MediaPlayerVolumePanelBrush cut
ListViewItem MouseScrollBarShadowBrush cut
ProgressBar ProgressBarBorderBrush Reuse but update its value based upon the
TransparentOutlineThemeBrush
ProgressBar ProgressBarFillBrush ProgressBarForegroundThemeBrush
ProgressBar ProgressBarTrackBrush ProgressBarBackgroundThemeBrush
ScrollBar ScrollBarButtonPointerOverBorderBr
ush
ScrollBarButtonPointerOverBorderThemeBrush
ScrollBar ScrollBarButtonPointerOverFillBrush ScrollBarButtonPointerOverBackgroundThemeBrush
ScrollBar ScrollBarButtonPressedBorderBrush ScrollBarButtonPressedBorderThemeBrush
ScrollBar ScrollBarButtonPressedFillBrush ScrollBarButtonPressedBackgroundThemeBrush
ScrollBar ScrollBarFaceBrush ScrollBarPanningBackgroundThemeBrush
ScrollBar ScrollBarGlyphArrowBrush ScrollBarButtonForegroundThemeBrush
ScrollBar ScrollBarGlyphArrowPointerOverBru
sh
ScrollBarButtonPointerOverForegroundThemeBrush
ScrollBar ScrollBarGlyphArrowPressedBrush ScrollBarButtonPressedForegroundThemeBrush
ScrollBar ScrollBarShadowBrush ScrollBarPanningBorderThemeBrush
ScrollBar ScrollBarThumbBorderBrush ScrollBarThumbBorderThemeBrush
ScrollBar ScrollBarThumbFillBrush ScrollBarThumbBackgroundThemeBrush
ScrollBar ScrollBarThumbPointerOverBorderBr
ush
ScrollBarThumbPointerOverBorderThemeBrush
ScrollBar ScrollBarThumbPointerOverFillBrush ScrollBarThumbPointerOverBackgroundThemeBrush
ScrollBar ScrollBarThumbPressedBorderBrush ScrollBarThumbPressedBorderThemeBrush
ScrollBar ScrollBarThumbPressedFillBrush ScrollBarThumbPressedBackgroundThemeBrush
ScrollBar ScrollBarTrackBorderBrush ScrollBarTrackBorderThemeBrush
ScrollBar ScrollBarTrackBrush ScrollBarTrackBackgroundThemeBrush
Slider SliderInlineTickMarkDisabledFillBrus
h
SliderTickMarkInlineDisabledForegroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —143
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
Slider SliderInlineTickMarkFillBrush SliderTickMarkInlineBackgroundThemeBrush
Slider SliderOutsideTickMarkDisabledFillBr
ush
SliderTickMarkOutsideDisabledForegroundThemeBrush
Slider SliderOutsideTickMarkFillBrush SliderTickmarkOutsideBackgroundThemeBrush
Slider SliderThumbDisabledBorderBrush SliderThumbDisabledBorderThemeBrush
Slider SliderThumbDisabledFillBrush SliderThumbDisabledBackgroundThemeBrush
Slider SliderThumbHoverBorderBrush SliderThumbPointerOverBorderThemeBrush
Slider SliderThumbHoverFillBrush SliderThumbPointerOverBackgroundThemeBrush
Slider SliderThumbNormalBorderBrush SliderThumbBorderThemeBrush
Slider SliderThumbNormalFillBrush SliderThumbBackgroundThemeBrush
Slider SliderThumbPressedBorderBrush SliderThumbPressedBorderThemeBrush
Slider SliderThumbPressedFillBrush SliderThumbPressedBackgroundThemeBrush
Slider SliderTrackDecreaseDisabledFillBrus
h
SliderTrackDecreaseDisabledBackgroundThemeBrush
Slider SliderTrackDecreaseNormalFillBrush SliderTrackDecreaseBackgroundThemeBrush
Slider SliderTrackDecreasePointerOverFillB
rush
SliderTrackDecreasePointerOverBackgroundThemeBrush
Slider SliderTrackDecreasePressedFillBrush SliderTrackDecreasePressedBackgroundThemeBrush
Slider SliderTrackDisabledFillBrush SliderTrackDisabledBackgroundThemeBrush
Slider SliderTrackNormalFillBrush SliderTrackBackgroundThemeBrush
Slider SliderTrackPointerOverFillBrush SliderTrackPointerOverBackgroundThemeBrush
Slider SliderTrackPressedFillBrush SliderTrackPressedBackgroundThemeBrush
TextBox TextBoxBorderBrush TextBoxBorderThemeBrush
TextBox TextBoxButtonBorderBrush TextBoxButtonBorderThemeBrush
TextBox TextBoxButtonFillBrush TextBoxButtonBackgroundThemeBrush
TextBox TextBoxButtonGlyphBrush TextBoxButtonForegroundThemeBrush
TextBox TextBoxButtonHoverBorderBrush TextBoxButtonPointerOverBorderThemeBrush
TextBox TextBoxButtonHoverFillBrush TextBoxButtonPointerOverBackgroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —144
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
TextBox TextBoxButtonHoverGlyphBrush TextBoxButtonPointerOverForegroundThemeBrush
TextBox TextBoxButtonPressedBorderBrush TextBoxButtonPressedBorderThemeBrush
TextBox TextBoxButtonPressedFillBrush TextBoxButtonPressedBackgroundThemeBrush
TextBox TextBoxButtonPressedGlyphBrush TextBoxButtonPressedForegroundThemeBrush
TextBox TextBoxDisabledBorderBrush TextBoxDisabledBorderThemeBrush
TextBox TextBoxDisabledFillBrush TextBoxDisabledBackgroundThemeBrush
TextBox TextBoxDisabledTextBrush TextBoxDisabledForegroundThemeBrush
TextBox TextBoxFillBrush TextBoxBackgroundThemeBrush
TextBox TextBoxTextBrush TextBoxForegroundThemeBrush
Thumb ThumbBorderBrush ThumbBorderThemeBrush
Thumb ThumbFillBrush ThumbBackgroundThemeBrush
Thumb ThumbPressedBrush ThumbPressedBackgroundThemeBrush
ToggleButton ToggleButtonBackgroundBrush ToggleButtonBackgroundThemeBrush
ToggleButton ToggleButtonBorderBrush ToggleButtonBorderThemeBrush
ToggleButton ToggleButtonCheckedFillBrush ToggleButtonCheckedBackgroundThemeBrush
ToggleButton ToggleButtonCheckedBorderBrush ToggleButtonCheckedBorderThemeBrush
ToggleButton ToggleButtonCheckedTextBrush ToggleButtonCheckedForegroundThemeBrush
ToggleButton ToggleButtonCheckedPointerOverFil
lBrush
ToggleButtonCheckedPointerOverBackgroundThemeBrush
ToggleButton ToggleButtonCheckedPointerOverB
orderBrush
ToggleButtonCheckedPointerOverBorderThemeBrush
ToggleButton ToggleButtonCheckedPressedFillBru
sh
ToggleButtonCheckedPressedBackgroundThemeBrush
ToggleButton ToggleButtonCheckedPressedBorde
rBrush
ToggleButtonCheckedPressedBorderThemeBrush
ToggleButton ToggleButtonCheckedPressedTextBr
ush
ToggleButtonCheckedPressedForegroundThemeBrush
ToggleButton ToggleButtonCheckedDisabledFillBr ToggleButtonCheckedDisabledBackgroundThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —145
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
ush
ToggleButton ToggleButtonCheckedDisabledTextB
rush
ToggleButtonCheckedDisabledForegroundThemeBrush
ToggleButton ToggleButtonDisabledBorderBrush ToggleButtonDisabledBorderThemeBrush
ToggleButton ToggleButtonPointerOverFillBrush ToggleButtonPointerOverBackgroundThemeBrush
ToggleSwitch ToggleSwitchCurtainBrush ToggleSwitchCurtainBackgroundThemeBrush
ToggleSwitch ToggleSwitchDisabledCurtainBrush ToggleSwitchCurtainDisabledBackgroundThemeBrush
ToggleSwitch ToggleSwitchDisabledForegroundBr
ush
ToggleSwitchDisabledForegroundThemeBrush
ToggleSwitch ToggleSwitchDisabledHeaderForegr
oundBrush
ToggleSwitchHeaderDisabledForegroundThemeBrush
ToggleSwitch ToggleSwitchForegroundBrush ToggleSwitchForegroundThemeBrush
ToggleSwitch ToggleSwitchHeaderForegroundBru
sh
ToggleSwitchHeaderForegroundThemeBrush
ToggleSwitch ToggleSwitchInnerBorderBrush ToggleSwitchTrackBorderThemeBrush
ToggleSwitch ToggleSwitchOuterBorderBrush ToggleSwitchOuterBorderBorderThemeBrush
ToggleSwitch ToggleSwitchOuterBorderDisabledBr
ush
ToggleSwitchOuterBorderDisabledBorderThemeBrush
ToggleSwitch ToggleSwitchPointerOverCurtainBru
sh
ToggleSwitchCurtainPointerOverBackgroundThemeBrush
ToggleSwitch ToggleSwitchPressedCurtainBrush ToggleSwitchCurtainPressedBackgroundThemeBrush
ToggleSwitch ToggleSwitchThumbBrush ToggleSwitchThumbBackgroundThemeBrush
ToggleSwitch ToggleSwitchThumbDisabledBrush ToggleSwitchThumbDisabledBackgroundThemeBrush
ToggleSwitch ToggleSwitchThumbPointerOverBru
sh
ToggleSwitchThumbPointerOverBackgroundThemeBrush
ToggleSwitch ToggleSwitchThumbPressedBrush ToggleSwitchThumbPressedBackgroundThemeBrush
ToggleSwitch ToggleSwitchThumbStrokeBrush ToggleSwitchThumbBorderThemeBrush
ToggleSwitch ToggleSwitchThumbStrokeDisabled
Brush
ToggleSwitchThumbDisabledBorderThemeBrush
ToggleSwitch ToggleSwitchThumbStrokePointerO
verBrush
ToggleSwitchThumbPointerOverBorderThemeBrush
Migrating your Windows 8 Consumer Preview app to Windows 8 Release Preview —146
May 31, 2012
© 2012 Microsoft. All rights reserved.
Area Current Value New Value
ToggleSwitch ToggleSwitchThumbStrokePressedBr
ush
ToggleSwitchThumbPressedForegroundThemeBrush
ToggleSwitch ToggleSwitchTrackBrush ToggleSwitchTrackBackgroundThemeBrush
ToggleSwitch ToggleSwitchTrackDisabledBrush ToggleSwitchTrackDisabledBackgroundThemeBrush
ToggleSwitch ToggleSwitchTrackPointerOverBrush ToggleSwitchTrackPointerOverBackgroundThemeBrush
ToggleSwitch ToggleSwitchTrackPressedBrush ToggleSwitchTrackPressedBackgroundThemeBrush
ToolTip ToolTipBackgroundBrush ToolTipBackgroundThemeBrush
ToolTip ToolTipBorderBrush ToolTipBorderThemeBrush
ToolTip ToolTipForegroundBrush ToolTipForegroundThemeBrush
TransparentOutlineBrush !!!!DELETE and replace with:
ProgressBar ProgressBarBorderThemeBrush
Slider SliderBorderThemeBrush