API changes for Windows 8.1(XAML)

  • Article

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This document lists API removals, functional changes, and optimizations introduced for Windows 8.1.

We’ve made significant changes and optimizations, to improve apps in Windows 8.1. These optimizations include changes to the XAML UI control, a new window size model, .NET profile changes, and more. You'll notice many optimizations without having to change your code, but some improvements do require changes. We encourage that you move away from deprecated APIs, to get the best performance from your app.

For other porting resources, see:

Important  For more information on API changes in Windows 8.1 related to programming with JavaScript and Internet Explorer, see API changes for Windows 8.1 (Windows Store apps using JavaScript and HTML).

 

Changes that affect specific APIs

The following table lists APIs that have behavior changes for Windows 8.1.

API Description
ApplicationModel.Background namespace The background tasks infrastructure validates parameters up front. For more info, see BackgroundTaskBuilder class and Quickstart: Create and register a background task.
ResourceLoader class The Windows Store app UI can be displayed on multiple monitors.
ApplicationViewSwitcher.DisableShowingMainViewOnActivation method Apps that create multiple core windows present the core window upon activation. For more info, see the Multiple Views Sample.
LanguageFontGroup class The fonts you used in your Windows Store apps may have changed for Windows 8.1.
DisplayProperties class Some of the DisplayProperties members are deprecated, but new ones have been added. This change may cause build errors and warnings if you use this API.
MediaCapture class This change involves high latency and low latency audio recording.
PlayToConnectionErrorEventArgs class When apps that use the PlayToConnectionErrorEventArgs object for "Play To" failures, troubleshooting is difficult because the PlayToConnectionError enumeration is not informative.
StorageFile.GetThumbnailAsync method In Windows 8.1, this method can return any size thumbnail.
CoreDispatcher.ProcessEvents method Calling this method recursively may cause your app to fail. Also, CoreDispatcher.ProcessEvents must be called only from the thread in which the CoreWindow was created. Calling this method from other threads will fail with an explicit error.
CoreDispatcher.AcceleratorKeyActivated event Keyboard focus tab navigation in Windows 8.1 will go to the correct object in the UI.
PropertyAnimation class Animating properties in Windows 8.1 is smoother when apps transition from one animation to another . This change also affects the Storyboard.Begin method.
Application.LoadComponent(Object, Uri) method In Windows 8.1, resource dictionaries aren't fully created during markup.
FlipView.UseTouchAnimationsForAllNavigation property In Windows 8.1, the move between items will be animated for all cases, not just touch.
Control.Focus method Setting programmatic focus has changed. For more info, see FocusState property.
FrameworkElement.LayoutUpdated event If an app attaches two listeners and removes one, only that listener gets removed.
ItemsPresenter.Header property The VerticalAlignment and HorizontalAlignment properties are honored, if set on the header. This change also affects the ItemsPresenter.HeaderTemplate property.
FrameworkElement.BaseUri property Can resolve file-specific URIs for XAML-defined template parts.
AutomationPeer.GetPatternCore method Controls can supply their own items peer behavior for Microsoft UI Automation.
UIElement.ManipulationMode property The ManipulationModes enumeration allows System to be combined with other values.
UIElement.ManipulationStarting event The ManipulationStarting event gets fired correctly. This change also affects the UIElement.ManipulationCompleted and Control.OnManipulationStarting events.
UIElement.PointerEntered event The PointerEntered event now fires correctly. This changes also affects the UIElement.PointerExited event.
UIElement.PointerWheelChanged event Direct Manipulation has added support for track pad gestures.
UIElement.RightTapped event The X/Y position values from event data of this event is ordered correctly in Windows 8.1. This change also affects the Control.OnRightTapped and RightTappedRoutedEventArgs.GetPosition methods.
VisualTransition class XAML transition animations turn off distracting animations automatically in Windows 8.1.
ListView class The XAML ListView and GridView controls display a list of items, and allow users to select items.
WebView class See the topic for significant behavior changes to the WebView control.
ComboBox.MaxDropDownHeight property This property is no longer ignored in Windows 8.1.
MediaElement class The MediaElement layout is like other XAML controls in Windows 8.1.
Image.ImageOpened event Starting in Windows 8.1, XAML will automatically reload images when the display scale changes. This change also affects the ImageFailed event.
TextBox.IsColorFontEnabled property Text controls in apps will not render multi-color fonts until they are rebuilt in Windows 8.1. This change also affects the TextBlock.IsColorFontEnabled, RichEditBox.IsColorFontEnabled, and RichTextBlock.IsColorFontEnabled properties.
ImageBrush.ImageSource property With the ImageBrush.ImageSource property, apps in Windows 8.1 will resolve URIs to the correct location in the app package.
VisualTreeHelper class In Windows 8.1, the VisualTreeHelper API validates that the caller is calling on the correct thread.
Storyboard.GetCurrentState method This method returns the correct value in Windows 8.1 for cases where animations use a BeginTime value.
BitmapImage.UriSource property The URI validation is removed from the setter in Windows 8.1.

 

Performance improvements

The following table lists performance improvements for Windows 8.1.

Change Description
Performance improvement of C# references Garbage collection speed has increased in Windows Store apps. For more info, see Improve garbage collection performance.
Quick restart after closing Apps are given up to five seconds to terminate, allowing them to restart quickly.
Surface all errors feature Errors raised in event handlers now propagate.
Suspension occurs at low priority To improve system responsiveness, apps are given lower-priority access to resources on suspension. For more info, see How to suspend an app.
Window size model We’ve added a new window size model in Windows 8.1 to support richer multitasking scenarios.
Correcting focus navigation in XAML list controls When the user tabs keyboard focus to the list control, the focus will go to the correct item. For more info, see FlipViewItem class.
ListView and GridView performance improvements All UIElement objects in the default control templates for GridViewItem and ListViewItem have been removed to significantly improve performance. For more info, see Improve startup time for apps with GridView and ListView controls.
Improving web security While apps built for Windows 8 can include http and https URIs in their application content URIs, apps built for Windows 8.1 may include only https URIs, except for dynamic ContentUriRules that are specified in their AppxManifest.xml file. For more info, see Windows 8.1 allows only https URIs, not http URIs from the Windows compatibility cookbook.
ItemsControl.PrepareContainerForItemOverride method The Content property will be set to the correct value when the CPU time becomes available.
VirtualSurfaceImageSource constructor The parameter validation maximum size has been changed from 100,000,000 to 17,000,000.

 

Mitigating changes

The following table lists changes that may impact your app running on Windows 8.1.

Change Description
LayoutAwarePage causes apps to break The LayoutAwarePage class is no longer included in Microsoft Visual Studio 2013 templates.
Portable Class Library The Portable Class Library is not available for Microsoft Visual Studio Express 2013 for Windows.
Visual C library changes The Visual C library has changes to assert() and exit(). For more info, see the Remarks section of Windows App Certification Kit tests.
Controls view is missing parts when filtered Elements are added to the UI Automation control view in Windows 8.1.
Event tracing for Windows (ETW) events ETW events are no longer raised in Windows 8.1.

 

Change descriptions

Controls view is missing parts when filtered

Parts of the XAML element tree do not show up in the filtered control view in the UI Automation tree. We fix this in Windows 8.1 by including more elements in the control view. However, some elements showing up in the control view shouldn’t be there. The new attached property, AutomationProperties.AccessibilityView, can be set on XAML elements, which lets an app developer specify elements that shouldn’t be in the control view. We updated built-in XAML control templates in Windows 8.1 to use the new property as appropriate. If a Windows 8 app has custom controls, or custom templates for the built-in controls, these need to set the new property.

Event tracing for Windows (ETW) events

In Windows 8, XAML traces ETW events in its compositor. In Windows 8.1, we replace that in-process compositor with DirectComposition, so those ETW events are no longer raised. Do not consider adding or removing traces a compatibility issue.

The LayoutAwarePage causes apps to break

In Windows 8, Microsoft Visual Studio templates define the LayoutAwarePage class to manage the visual states based on the ApplicationViewState. In Windows 8.1, ApplicationViewState is deprecated and LayoutAwarePage is no longer included in the Visual Studio templates for Windows Store apps. Continuing to use the LayoutAwarePage code can break your app. To fix this, rewrite your view to accommodate the new minimum resolution, and create events based on the window size. If you update your app to different sizes, you must handle the Window.SizeChanged event to adapt the UI of your app to the new size. We recommend that you stop using the LayoutAwarePage class, and inherit the classes directly from the Page class.

Here's how to stop using LayoutAwarePage:

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    base.OnNavigatedTo(e);
    this.Loaded += PageLoaded;
    this.Unloaded += PageUnloaded;
 }

 private void PageUnloaded(object sender, RoutedEventArgs e)
 {
     Window.Current.SizeChanged -= Window_SizeChanged;
 }

 private void PageLoaded(object sender, RoutedEventArgs e)
 {
     Window.Current.SizeChanged += Window_SizeChanged;
 }

 private void Window_SizeChanged(object sender, Windows.UI.Core.WindowSizeChangedEventArgs e)
 {
     if (e.Size.Width <= 500)
     {
     //VisualStateManager.GoToState(this, state.State, transitions);
     }
     else if (e.Size.Height > e.Size.Width)
     {
     //VisualStateManager.GoToState(this, state.State, transitions);
     }
     else
     {
     //VisualStateManager.GoToState(this, state.State, transitions);
     }
 }

Portable Class Library

The Portable Class Library is available only for Microsoft Visual Studio Professional 2013. It is not available in Visual Studio Express 2013 for Windows.

ListView and GridView performance improvements

GroupStyle class

Three properties of the GroupStyle class for ListView and GridView are deprecated and ignored. The properties Panel, ContainerStyle, and ContainerStyleSelector of GroupStyle are no longer honored when ItemsPanel is an ItemsStackPanel. ListView and GridView will be laid out like a traditional list—from top to bottom. Thus, the layout or appearance of items within a group could change in a Windows 8 app that is recompiled for Windows 8.1 if the app does not explicitly set ItemsPanel but set Panel, ContainerStyle, and ContainerStyleSelector. An app that has taken a dependency on the internal structure and types of default ListView objects can crash because the type of ItemsPanel will change and GroupItems will not be created when GroupStyle.Panel is an ItemsStackPanel. This crash would most likely occur when walking the visual tree.

Avoid this by setting ItemsPanel back to the Windows 8 panel (VirtualizingStackPanel) or removing assumptions about the visual tree structure.

ItemsPanel property

The default ItemsPanel property is changed in Windows 8.1. In Windows 8, the default ItemsPanel for ListView is VirtualizingStackPanel, and the default ItemsPanel for GridView is WrapGrid. In Windows 8.1, those defaults are now ItemsStackPanel for ListView and ItemsWrapGrid for GridView. This change may cause crashes when walking the visual tree. The workaround is to set the ItemsPanel property back to the Windows 8 default value.

Quick restart after closing

In Windows 8.1, if the user closes an app and then immediately restarts it, the closed app is given up to five seconds to complete its termination before it restarts. In Windows 8, the app terminates immediately upon restart.

Surface all errors feature

In Windows 8.1, errors raised in event handlers now propagate. Errors that are unhandled trigger application termination. Before termination, the CoreApplication::UnhandledErrorDetected event fires, giving the developer the opportunity to handle the error without termination. Note that this event does not replace the XAML UnhandledException event. Unhandled errors in Windows Store apps using XAML raise both of these events and the developer is free to use whichever one is better suited to the app.

Window size model

We’ve added a new window size model in Windows 8.1 to support richer multitasking scenarios. The concept of discrete view states is removed and the snapped state is no longer required. Instead, apps can be sized continuously to any size down to their minimum size. An app can either have a minimum width of 500px or 320px. By default, the minimum size of an app is 500px.

The Windows 8 ApplicationView.Value property and ApplicationView.TryUnsnap method are deprecated, so you will receive compiler warnings if your app uses them. An app should register for the window resize event to know when to update the layout. However, instead of calling ApplicationView.Value to find out which view state the app is in, use the Window.Current and Window.Bounds property to get the general window size, or the ApplicationView.GetForCurrentView and ApplicationView.Orientation property to get the orientation. In Windows 8.1, it is up to the app designer to decide what window size thresholds and media queries the app makes to update the app layout.

Here are some possible ways to port your code.

Viewing general window size:

Windows 8

private void WindowSizeChanged(object sender, WindowSizeChangedEventArgs e) {
    // Get view state
    ApplicationViewState currentViewState = ApplicationView.Value;
 
    if (currentViewState == ApplicationViewState.FullScreenLandscape) {
       // Full screen Landscape layout
    }
    else if (currentViewState == ApplicationViewState.FullScreenPortrait) {
       // Full screen Portrait layout
    }
    else if (currentViewState == ApplicationViewState.Filled) {
       // Filled layout
    }
    else if (currentViewState == ApplicationViewState.Snapped) {
       // Snapped layout
    }
}

Windows 8.1

private void WindowSizeChanged(object sender, WindowSizeChangedEventArgs e) {
        // Get window size
        var WindowWidth = Window.Current.Bounds.Width;
 
        // App code to change layout based on window width
}

Viewing orientation:

Windows 8

private void WindowSizeChanged(object sender, WindowSizeChangedEventArgs e) {
    // Get view state
    ApplicationViewState currentViewState = ApplicationView.Value;
 
    if (currentViewState == ApplicationViewState.FullScreenLandscape || currentViewState == ApplicationViewState.Filled) {
       // Landscape layouts
    }
    else if (currentViewState == ApplicationViewState.FullScreenPortrait) {
       // Portrait layouts
    }
}

Windows 8.1

private void WindowSizeChanged(object sender, WindowSizeChangedEventArgs e) {
    // Get window orientation
    ApplicationViewOrientation winOrientation = ApplicationView.GetForCurrentView().Orientation;
 
    if (winOrientation == ApplicationViewOrientation.Landscape) {
       // Landscape layouts
    }
    else if (winOrientation == ApplicationViewOrientation.Portrait) {
       // Portrait layouts
    }
}

Retarget your Windows Store app to Windows 8.1

Updated samples

DirectX programming

API changes for Windows 8.1 (Windows Store apps using JavaScript and HTML)