Category Archives: apis

Auto Added by WPeMatico

Windows 10 SDK Preview Build 17035 now available

Today, we released a new Windows 10 Preview Build of the SDK to be used in conjunction with Windows 10 Insider Preview (Build 17035 or greater). The Preview SDK Build 17035 contains bug fixes and under development changes to the API surface area.
The Preview SDK can be downloaded from developer section on Windows Insider.
For feedback and updates to the known issues, please see the developer forum. For new developer feature requests, head over to our Windows Platform UserVoice.
Things to note:
This build works in conjunction with previously released SDKs and Visual Studio 2017. You can install this SDK and still also continue to submit your apps that target Windows 10 Creators build or earlier to the store.
The Windows SDK will now formally only be supported by Visual Studio 2017 and greater. You can download the Visual Studio 2017 here.
Known Issues:
Installation on an operating system that is not a Windows 10 Insider Preview  build is not supported and may fail.
What’s New:
C++/WinRT Now Available:
The C++/WinRT headers and cppwinrt compiler (cppwinrt.exe) are now included in the Windows SDK. The compiler comes in handy if you need to consume a third-party WinRT component or if you need to author your own WinRT components with C++/WinRT. The easiest way to get working with it after installing the Windows Insider Preview SDK is to start the Visual Studio Developer Command Prompt and run the compiler in that environment. Authoring support is currently experimental and subject to change. Stay tuned as we will publish more detailed instructions on how to use the compiler in the coming week. The ModernCPP blog has a deeper dive into the CppWinRT compiler. Please give us feedback by creating an issue at: https://github.com/microsoft/cppwinrt.
Breaking Changes
New MIDL key words. 
As a part of the “modernizing IDL” effort, several new keywords are added to the midlrt tool. These new keywords will cause build breaks if they are encountered in IDL files.
The new keywords are:
event
set
get
partial
unsealed
overridable
protected
importwinmd
If any of these keywords are used as an identifier, it will generate a build failure indicating a syntax error.
The error will be similar to:
1 >d:ossrconecorecomcombaseunittestastatestserverstestserver6idlremreleasetest.idl(12) : error MIDL2025 : [msg]syntax error [context]: expecting a declarator or * near “)”
To fix this, modify the identifier in error to an “@” prefix in front of the identifier. That will cause MIDL to treat the offending element as an identifier instead of a keyword.
API Updates and Additions
When targeting new APIs, consider writing your app to be adaptive in order to run correctly on the widest number of Windows 10 devices. Please see Dynamically detecting features with API contracts (10 by 10) for more information.
The following APIs have been added to the platform since the release of 16299.

namespace Windows.ApplicationModel {
public enum StartupTaskState {
EnabledByPolicy = 4,
}
}
namespace Windows.ApplicationModel.Background {
public sealed class MobileBroadbandPcoDataChangeTrigger : IBackgroundTrigger
}
namespace Windows.ApplicationModel.Calls {
public enum PhoneCallMedia {
AudioAndRealTimeText = 2,
}
public sealed class VoipCallCoordinator {
VoipPhoneCall RequestNewAppInitiatedCall(string context, string contactName, string contactNumber, string serviceName, VoipPhoneCallMedia media);
VoipPhoneCall RequestNewIncomingCall(string context, string contactName, string contactNumber, Uri contactImage, string serviceName, Uri brandingImage, string callDetails, Uri ringtone, VoipPhoneCallMedia media, TimeSpan ringTimeout, string contactRemoteId);
}
public sealed class VoipPhoneCall {
void NotifyCallAccepted(VoipPhoneCallMedia media);
}
}
namespace Windows.ApplicationModel.Chat {
public sealed class RcsManagerChangedEventArgs
public enum RcsManagerChangeType
public sealed class RcsNotificationManager
}
namespace Windows.ApplicationModel.UserActivities {
public sealed class UserActivity {
public UserActivity();
}
public sealed class UserActivityChannel {
public static void DisableAutoSessionCreation();
}
public sealed class UserActivityVisualElements {
string AttributionDisplayText { get; set; }
}
}
namespace Windows.Devices.PointOfService {
public sealed class BarcodeScannerReport {
public BarcodeScannerReport(uint scanDataType, IBuffer scanData, IBuffer scanDataLabel);
}
public sealed class ClaimedBarcodeScanner : IClosable {
void HideVideoPreview();
IAsyncOperation<bool> ShowVideoPreviewAsync();
}
public sealed class UnifiedPosErrorData {
public UnifiedPosErrorData(string message, UnifiedPosErrorSeverity severity, UnifiedPosErrorReason reason, uint extendedReason);
}
}
namespace Windows.Globalization {
public static class ApplicationLanguages {
public static IVectorView<string> GetLanguagesForUser(User user);
}
public sealed class Language {
LanguageLayoutDirection LayoutDirection { get; }
}
public enum LanguageLayoutDirection
}
namespace Windows.Graphics.Imaging {
public enum BitmapPixelFormat {
P010 = 104,
}
}
namespace Windows.Management.Deployment {
public sealed class PackageManager {
IAsyncOperationWithProgress<DeploymentResult, DeploymentProgress> RequestAddPackageAsync(Uri packageUri, IIterable<Uri> dependencyPackageUris, DeploymentOptions deploymentOptions, PackageVolume targetVolume, IIterable<string> optionalPackageFamilyNames, IIterable<Uri> relatedPackageUris, IIterable<Uri> packageUrisToInstall);
}
}
namespace Windows.Media.Audio {
public sealed class AudioGraph : IClosable {
IAsyncOperation<CreateMediaSourceAudioInputNodeResult> CreateMediaSourceAudioInputNodeAsync(MediaSource mediaSource);
IAsyncOperation<CreateMediaSourceAudioInputNodeResult> CreateMediaSourceAudioInputNodeAsync(MediaSource mediaSource, AudioNodeEmitter emitter);
}
public sealed class AudioGraphSettings {
double MaxPlaybackSpeedFactor { get; set; }
}
public sealed class CreateMediaSourceAudioInputNodeResult
public sealed class MediaSourceAudioInputNode : IAudioInputNode, IAudioInputNode2, IAudioNode, IClosable
public enum MediaSourceAudioInputNodeCreationStatus
}
namespace Windows.Media.Capture {
public sealed class CapturedFrame : IClosable, IContentTypeProvider, IInputStream, IOutputStream, IRandomAccessStream, IRandomAccessStreamWithContentType {
BitmapPropertySet BitmapProperties { get; }
CapturedFrameControlValues ControlValues { get; }
}
}
namespace Windows.Media.Capture.Frames {
public sealed class AudioMediaFrame
public sealed class MediaFrameFormat {
AudioEncodingProperties AudioEncodingProperties { get; }
}
public sealed class MediaFrameReference : IClosable {
AudioMediaFrame AudioMediaFrame { get; }
}
public sealed class MediaFrameSourceController {
AudioDeviceController AudioDeviceController { get; }
}
public enum MediaFrameSourceKind {
Audio = 4,
}
}
namespace Windows.Media.Core {
public sealed class MediaBindingEventArgs {
void SetDownloadOperation(DownloadOperation downloadOperation);
}
public sealed class MediaSource : IClosable, IMediaPlaybackSource {
DownloadOperation DownloadOperation { get; }
public static MediaSource CreateFromDownloadOperation(DownloadOperation downloadOperation);
}
}
namespace Windows.Media.Devices {
public sealed class VideoDeviceController : IMediaDeviceController {
VideoTemporalDenoisingControl VideoTemporalDenoisingControl { get; }
}
public sealed class VideoTemporalDenoisingControl
public enum VideoTemporalDenoisingMode
}
namespace Windows.Media.DialProtocol {
public sealed class DialReceiverApp {
IAsyncOperation<string> GetUniqueDeviceNameAsync();
}
}
namespace Windows.Media.MediaProperties {
public static class MediaEncodingSubtypes {
public static string P010 { get; }
}
public enum MediaPixelFormat {
P010 = 2,
}
}
namespace Windows.Media.Playback {
public sealed class MediaPlaybackSession {
MediaRotation PlaybackRotation { get; set; }
MediaPlaybackSessionOutputDegradationPolicyState GetOutputDegradationPolicyState();
}
public sealed class MediaPlaybackSessionOutputDegradationPolicyState
public enum MediaPlaybackSessionVideoConstrictionReason
}
namespace Windows.Media.Streaming.Adaptive {
public sealed class AdaptiveMediaSourceDiagnosticAvailableEventArgs {
string ResourceContentType { get; }
IReference<TimeSpan> ResourceDuration { get; }
}
public sealed class AdaptiveMediaSourceDownloadCompletedEventArgs {
string ResourceContentType { get; }
IReference<TimeSpan> ResourceDuration { get; }
}
public sealed class AdaptiveMediaSourceDownloadFailedEventArgs {
string ResourceContentType { get; }
IReference<TimeSpan> ResourceDuration { get; }
}
public sealed class AdaptiveMediaSourceDownloadRequestedEventArgs {
string ResourceContentType { get; }
IReference<TimeSpan> ResourceDuration { get; }
}
}
namespace Windows.Networking.BackgroundTransfer {
public sealed class DownloadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority {
void MakeCurrentInTransferGroup();
}
public sealed class UploadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority {
void MakeCurrentInTransferGroup();
}
}
namespace Windows.Networking.Connectivity {
public sealed class CellularApnContext {
string ProfileName { get; set; }
}
public sealed class ConnectionProfileFilter {
IReference<Guid> PurposeGuid { get; set; }
}
public sealed class WwanConnectionProfileDetails {
WwanNetworkIPKind IPKind { get; }
IVectorView<Guid> PurposeGuids { get; }
}
public enum WwanNetworkIPKind
}
namespace Windows.Networking.NetworkOperators {
public sealed class MobileBroadbandAntennaSar {
public MobileBroadbandAntennaSar(int antennaIndex, int sarBackoffIndex);
}
public sealed class MobileBroadbandModem {
IAsyncOperation<MobileBroadbandPco> TryGetPcoAsync();
}
public sealed class MobileBroadbandModemIsolation
public sealed class MobileBroadbandPco
public sealed class MobileBroadbandPcoDataChangeTriggerDetails
}
namespace Windows.Networking.Sockets {
public sealed class ServerMessageWebSocket : IClosable
public sealed class ServerMessageWebSocketControl
public sealed class ServerMessageWebSocketInformation
public sealed class ServerStreamWebSocket : IClosable
public sealed class ServerStreamWebSocketInformation
}
namespace Windows.Networking.Vpn {
public sealed class VpnNativeProfile : IVpnProfile {
string IDi { get; set; }
VpnPayloadIdType IdiType { get; set; }
string IDr { get; set; }
VpnPayloadIdType IdrType { get; set; }
bool IsImsConfig { get; set; }
string PCscf { get; }
}
public enum VpnPayloadIdType
}
namespace Windows.Security.Authentication.Identity.Provider {
public enum SecondaryAuthenticationFactorAuthenticationMessage {
CanceledByUser = 22,
CenterHand = 23,
ConnectionRequired = 20,
DeviceUnavaliable = 28,
MoveHandCloser = 24,
MoveHandFarther = 25,
PlaceHandAbove = 26,
RecognitionFailed = 27,
TimeLimitExceeded = 21,
}
}
namespace Windows.Services.Maps {
public sealed class MapRouteDrivingOptions {
IReference<DateTime> DepartureTime { get; set; }
}
}
namespace Windows.System {
public sealed class AppActivationResult
public sealed class AppDiagnosticInfo {
IAsyncOperation<AppActivationResult> ActivateAsync();
}
public sealed class AppResourceGroupInfo {
IAsyncOperation<bool> TryResumeAsync();
IAsyncOperation<bool> TrySuspendAsync();
IAsyncOperation<bool> TryTerminateAsync();
}
}
namespace Windows.System.Diagnostics.DevicePortal {
public sealed class DevicePortalConnection {
ServerMessageWebSocket GetServerMessageWebSocketForRequest(HttpRequestMessage request);
ServerMessageWebSocket GetServerMessageWebSocketForRequest(HttpRequestMessage request, SocketMessageType messageType, string protocol);
ServerMessageWebSocket GetServerMessageWebSocketForRequest(HttpRequestMessage request, SocketMessageType messageType, string protocol, uint outboundBufferSizeInBytes, uint maxMessageSize, MessageWebSocketReceiveMode receiveMode);
ServerStreamWebSocket GetServerStreamWebSocketForRequest(HttpRequestMessage request);
ServerStreamWebSocket GetServerStreamWebSocketForRequest(HttpRequestMessage request, string protocol, uint outboundBufferSizeInBytes, bool noDelay);
}
public sealed class DevicePortalConnectionRequestReceivedEventArgs {
bool IsWebSocketUpgradeRequest { get; }
IVectorView<string> WebSocketProtocolsRequested { get; }
Deferral GetDeferral();
}
}
namespace Windows.System.RemoteSystems {
public static class KnownRemoteSystemCapabilities {
public static string NearShare { get; }
}
}
namespace Windows.System.UserProfile {
public static class GlobalizationPreferences {
public static GlobalizationPreferencesForUser GetForUser(User user);
}
public sealed class GlobalizationPreferencesForUser
}
namespace Windows.UI.Composition {
public class CompositionLight : CompositionObject {
bool IsEnabled { get; set; }
}
public sealed class Compositor : IClosable {
string Comment { get; set; }
}
public sealed class PointLight : CompositionLight {
Vector2 AttenuationCutoff { get; set; }
}
public sealed class SpotLight : CompositionLight {
Vector2 AttenuationCutoff { get; set; }
}
}
namespace Windows.UI.Composition.Core {
public sealed class CompositorController : IClosable
}
namespace Windows.UI.Xaml {
public sealed class BringIntoViewOptions {
IReference<double> HorizontalAlignmentRatio { get; set; }
Point Offset { get; set; }
IReference<double> VerticalAlignmentRatio { get; set; }
}
public sealed class BringIntoViewRequestedEventArgs : RoutedEventArgs
public sealed class EffectiveViewportChangedEventArgs
public class FrameworkElement : UIElement {
event TypedEventHandler<FrameworkElement, EffectiveViewportChangedEventArgs> EffectiveViewportChanged;
void InvalidateViewport();
virtual bool IsViewport();
}
public class UIElement : DependencyObject {
public static RoutedEvent BringIntoViewRequestedEvent { get; }
KeyboardAcceleratorPlacementMode KeyboardAcceleratorPlacementMode { get; set; }
public static DependencyProperty KeyboardAcceleratorPlacementModeProperty { get; }
DependencyObject KeyboardAcceleratorToolTipTarget { get; set; }
public static DependencyProperty KeyboardAcceleratorToolTipTargetProperty { get; }
DependencyObject KeyTipTarget { get; set; }
public static DependencyProperty KeyTipTargetProperty { get; }
event TypedEventHandler<UIElement, BringIntoViewRequestedEventArgs> BringIntoViewRequested;
virtual void OnBringIntoViewRequested(BringIntoViewRequestedEventArgs e);
virtual void OnKeyboardAcceleratorInvoked(KeyboardAcceleratorInvokedEventArgs args);
}
}
namespace Windows.UI.Xaml.Automation.Peers {
public sealed class AutoSuggestBoxAutomationPeer : FrameworkElementAutomationPeer, IInvokeProvider {
void Invoke();
}
}
namespace Windows.UI.Xaml.Controls {
public class AppBarButton : Button, ICommandBarElement, ICommandBarElement2 {
string KeyboardAcceleratorText { get; set; }
public static DependencyProperty KeyboardAcceleratorTextProperty { get; }
AppBarButtonTemplateSettings TemplateSettings { get; }
}
public class AppBarToggleButton : ToggleButton, ICommandBarElement, ICommandBarElement2 {
string KeyboardAcceleratorText { get; set; }
public static DependencyProperty KeyboardAcceleratorTextProperty { get; }
AppBarToggleButtonTemplateSettings TemplateSettings { get; }
}
public class MenuFlyoutItem : MenuFlyoutItemBase {
string KeyboardAcceleratorText { get; set; }
public static DependencyProperty KeyboardAcceleratorTextProperty { get; }
MenuFlyoutItemTemplateSettings TemplateSettings { get; }
}
public class NavigationView : ContentControl {
string PaneTitle { get; set; }
public static DependencyProperty PaneTitleProperty { get; }
event TypedEventHandler<NavigationView, object> PaneClosed;
event TypedEventHandler<NavigationView, NavigationViewPaneClosingEventArgs> PaneClosing;
event TypedEventHandler<NavigationView, object> PaneOpened;
event TypedEventHandler<NavigationView, object> PaneOpening;
}
public sealed class NavigationViewPaneClosingEventArgs
public enum WebViewPermissionType {
Screen = 5,
}
}
namespace Windows.UI.Xaml.Controls.Maps {
public sealed class MapControl : Control {
string Region { get; set; }
public static DependencyProperty RegionProperty { get; }
}
public class MapElement : DependencyObject {
bool IsEnabled { get; set; }
public static DependencyProperty IsEnabledProperty { get; }
}
}
namespace Windows.UI.Xaml.Controls.Primitives {
public sealed class AppBarButtonTemplateSettings : DependencyObject
public sealed class AppBarToggleButtonTemplateSettings : DependencyObject
public sealed class MenuFlyoutItemTemplateSettings : DependencyObject
}
namespace Windows.UI.Xaml.Input {
public sealed class KeyboardAcceleratorInvokedEventArgs {
KeyboardAccelerator KeyboardAccelerator { get; }
}
public enum KeyboardAcceleratorPlacementMode
}

Windows 10 SDK Preview Build 17025

Today, we released a new Windows 10 Preview Build of the SDK to be used in conjunction with Windows 10 Insider Preview (Build 17025 or greater). The Preview SDK Build 17025 contains bug fixes and under development changes to the API surface area.
The Preview SDK can be downloaded from developer section on Windows Insider.
For feedback and updates to the known issues, please see the developer forum.  For new developer feature requests, head over to our Windows Platform UserVoice.
Things to note:
This build works in conjunction with previously released SDKs and Visual Studio 2017. You can install this SDK and still also continue to submit your apps that target Windows 10 Creators build or earlier to the store.
The Windows SDK will now formally only be supported by Visual Studio 2017 and greater. You can download the Visual Studio 2017 here.
Known Issues
Installation on an operating system that is not a Windows 10 Insider Preview build is not supported and may fail.
 Breaking Changes
New MIDL key words.As a part of the “modernizing IDL” effort, several new keywords are added to the midlrt tool. These new keywords will cause build breaks if they are encountered in IDL files.
The new keywords are:
event
set
get
partial
unsealed
overridable
protected
importwinmd
If any of these keywords are used as an identifier, it will generate a build failure indicating a syntax error.
The error will be similar to:
1
>d:ossrconecorecomcombaseunittestastatestserverstestserver6idlremreleasetest.idl
(12) : error MIDL2025 : [msg]syntax error [context]: expecting a declarator or * near “)”
To fix this, modify the identifier in error to an “@” prefix in front of the identifier. That will cause MIDL to treat the offending element as an identifier instead of a keyword.
API Updates and Additions
When targeting new APIs, consider writing your app to be adaptive in order to run correctly on the widest number of Windows 10 devices. Please see Dynamically detecting features with API contracts (10 by 10) for more information.
The following APIs have been added to the platform since the release of 16299.

namespace Windows.ApplicationModel {
public enum StartupTaskState {
EnabledByPolicy = 4,
}
}
namespace Windows.ApplicationModel.Background {
public sealed class MobileBroadbandPcoDataChangeTrigger : IBackgroundTrigger
}
namespace Windows.ApplicationModel.Calls {
public enum PhoneCallMedia {
AudioAndRealTimeText = 2,
}
public sealed class VoipCallCoordinator {
VoipPhoneCall RequestNewAppInitiatedCall(string context, string contactName, string contactNumber, string serviceName, VoipPhoneCallMedia media);
VoipPhoneCall RequestNewIncomingCall(string context, string contactName, string contactNumber, Uri contactImage, string serviceName, Uri brandingImage, string callDetails, Uri ringtone, VoipPhoneCallMedia media, TimeSpan ringTimeout, string contactRemoteId);
}
public sealed class VoipPhoneCall {
void NotifyCallAccepted(VoipPhoneCallMedia media);
}
}
namespace Windows.ApplicationModel.UserActivities {
public sealed class UserActivity {
public UserActivity();
}
public sealed class UserActivityChannel {
public static void DisableAutoSessionCreation();
}
public sealed class UserActivityVisualElements {
string AttributionDisplayText { get; set; }
}
}
namespace Windows.Devices.PointOfService {
public sealed class BarcodeScannerReport {
public BarcodeScannerReport(uint scanDataType, IBuffer scanData, IBuffer scanDataLabel);
}
public sealed class ClaimedBarcodeScanner : IClosable {
void HideVideoPreview();
IAsyncOperation<bool> ShowVideoPreviewAsync();
}
public sealed class UnifiedPosErrorData {
public UnifiedPosErrorData(string message, UnifiedPosErrorSeverity severity, UnifiedPosErrorReason reason, uint extendedReason);
}
}
namespace Windows.Globalization {
public static class ApplicationLanguages {
public static IVectorView<string> GetLanguagesForUser(User user);
}
public sealed class Language {
LanguageLayoutDirection LayoutDirection { get; }
}
public enum LanguageLayoutDirection
}
namespace Windows.Graphics.Imaging {
public enum BitmapPixelFormat {
P010 = 104,
}
}
namespace Windows.Management.Deployment {
public sealed class PackageManager {
IAsyncOperationWithProgress<DeploymentResult, DeploymentProgress> RequestAddPackageAsync(Uri packageUri, IIterable<Uri> dependencyPackageUris, DeploymentOptions deploymentOptions, PackageVolume targetVolume, IIterable<string> optionalPackageFamilyNames, IIterable<Uri> relatedPackageUris, IIterable<Uri> packageUrisToInstall);
}
}
namespace Windows.Media.Capture {
public sealed class CapturedFrame : IClosable, IContentTypeProvider, IInputStream, IOutputStream, IRandomAccessStream, IRandomAccessStreamWithContentType {
BitmapPropertySet BitmapProperties { get; }
CapturedFrameControlValues ControlValues { get; }
}
}
namespace Windows.Media.Core {
public sealed class MediaBindingEventArgs {
void SetDownloadOperation(DownloadOperation downloadOperation);
}
public sealed class MediaSource : IClosable, IMediaPlaybackSource {
DownloadOperation DownloadOperation { get; }
public static MediaSource CreateFromDownloadOperation(DownloadOperation downloadOperation);
}
}
namespace Windows.Media.Devices {
public sealed class VideoDeviceController : IMediaDeviceController {
VideoTemporalDenoisingControl VideoTemporalDenoisingControl { get; }
}
public sealed class VideoTemporalDenoisingControl
public enum VideoTemporalDenoisingMode
}
namespace Windows.Media.MediaProperties {
public static class MediaEncodingSubtypes {
public static string P010 { get; }
}
public enum MediaPixelFormat {
P010 = 2,
}
}
namespace Windows.Networking.BackgroundTransfer {
public sealed class DownloadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority {
void MakeCurrentInTransferGroup();
}
public sealed class UploadOperation : IBackgroundTransferOperation, IBackgroundTransferOperationPriority {
void MakeCurrentInTransferGroup();
}
}
namespace Windows.Networking.Connectivity {
public sealed class CellularApnContext {
string ProfileName { get; set; }
}
public sealed class ConnectionProfileFilter {
IReference<Guid> PurposeGuid { get; set; }
}
public sealed class WwanConnectionProfileDetails {
WwanNetworkIPKind IPKind { get; }
IVectorView<Guid> PurposeGuids { get; }
}
public enum WwanNetworkIPKind
}
namespace Windows.Networking.NetworkOperators {
public sealed class MobileBroadbandAntennaSar {
public MobileBroadbandAntennaSar(int antennaIndex, int sarBackoffIndex);
}
public sealed class MobileBroadbandModem {
IAsyncOperation<MobileBroadbandPco> TryGetPcoAsync();
}
public sealed class MobileBroadbandModemIsolation
public sealed class MobileBroadbandPco
public sealed class MobileBroadbandPcoDataChangeTriggerDetails
}
namespace Windows.Networking.Sockets {
public sealed class ServerMessageWebSocket : IClosable
public sealed class ServerMessageWebSocketControl
public sealed class ServerMessageWebSocketInformation
public sealed class ServerStreamWebSocket : IClosable
public sealed class ServerStreamWebSocketInformation
}
namespace Windows.Security.Authentication.Identity.Provider {
public enum SecondaryAuthenticationFactorAuthenticationMessage {
CanceledByUser = 22,
CenterHand = 23,
ConnectionRequired = 20,
DeviceUnavaliable = 28,
MoveHandCloser = 24,
MoveHandFarther = 25,
PlaceHandAbove = 26,
RecognitionFailed = 27,
TimeLimitExceeded = 21,
}
}
namespace Windows.Services.Maps {
public sealed class MapRouteDrivingOptions {
IReference<DateTime> DepartureTime { get; set; }
}
}
namespace Windows.System {
public sealed class AppActivationResult
public sealed class AppDiagnosticInfo {
IAsyncOperation<AppActivationResult> ActivateAsync();
}
public sealed class AppResourceGroupInfo {
IAsyncOperation<bool> TryResumeAsync();
IAsyncOperation<bool> TrySuspendAsync();
IAsyncOperation<bool> TryTerminateAsync();
}
}
namespace Windows.System.Diagnostics.DevicePortal {
public sealed class DevicePortalConnection {
ServerMessageWebSocket GetServerMessageWebSocketForRequest(HttpRequestMessage request);
ServerMessageWebSocket GetServerMessageWebSocketForRequest(HttpRequestMessage request, SocketMessageType messageType, string protocol);
ServerMessageWebSocket GetServerMessageWebSocketForRequest(HttpRequestMessage request, SocketMessageType messageType, string protocol, uint outboundBufferSizeInBytes, uint maxMessageSize, MessageWebSocketReceiveMode receiveMode);
ServerStreamWebSocket GetServerStreamWebSocketForRequest(HttpRequestMessage request);
ServerStreamWebSocket GetServerStreamWebSocketForRequest(HttpRequestMessage request, string protocol, uint outboundBufferSizeInBytes, bool noDelay);
}
public sealed class DevicePortalConnectionRequestReceivedEventArgs {
bool IsWebSocketUpgradeRequest { get; }
IVectorView<string> WebSocketProtocolsRequested { get; }
Deferral GetDeferral();
}
}
namespace Windows.System.RemoteSystems {
public static class KnownRemoteSystemCapabilities {
public static string NearShare { get; }
}
}
namespace Windows.System.UserProfile {
public static class GlobalizationPreferences {
public static GlobalizationPreferencesForUser GetForUser(User user);
}
public sealed class GlobalizationPreferencesForUser
}
namespace Windows.UI.Composition {
public class CompositionLight : CompositionObject {
bool IsEnabled { get; set; }
}
public sealed class Compositor : IClosable {
string Comment { get; set; }
}
public sealed class PointLight : CompositionLight {
Vector2 AttenuationCutoff { get; set; }
}
public sealed class SpotLight : CompositionLight {
Vector2 AttenuationCutoff { get; set; }
}
}
namespace Windows.UI.Composition.Core {
public sealed class CompositorController : IClosable
}
namespace Windows.UI.Xaml {
public sealed class BringIntoViewOptions {
IReference<double> HorizontalAlignmentRatio { get; set; }
Point Offset { get; set; }
IReference<double> VerticalAlignmentRatio { get; set; }
}
public sealed class BringIntoViewRequestedEventArgs : RoutedEventArgs
public sealed class EffectiveViewportChangedEventArgs
public class FrameworkElement : UIElement {
event TypedEventHandler<FrameworkElement, EffectiveViewportChangedEventArgs> EffectiveViewportChanged;
void InvalidateViewport();
virtual bool IsViewport();
}
public class UIElement : DependencyObject {
public static RoutedEvent BringIntoViewRequestedEvent { get; }
KeyboardAcceleratorPlacementMode KeyboardAcceleratorPlacementMode { get; set; }
public static DependencyProperty KeyboardAcceleratorPlacementModeProperty { get; }
DependencyObject KeyboardAcceleratorToolTipTarget { get; set; }
public static DependencyProperty KeyboardAcceleratorToolTipTargetProperty { get; }
DependencyObject KeyTipTarget { get; set; }
public static DependencyProperty KeyTipTargetProperty { get; }
event TypedEventHandler<UIElement, BringIntoViewRequestedEventArgs> BringIntoViewRequested;
virtual void OnBringIntoViewRequested(BringIntoViewRequestedEventArgs e);
virtual void OnKeyboardAcceleratorInvoked(KeyboardAcceleratorInvokedEventArgs args);
}
}
namespace Windows.UI.Xaml.Automation.Peers {
public sealed class AutoSuggestBoxAutomationPeer : FrameworkElementAutomationPeer, IInvokeProvider {
void Invoke();
}
}
namespace Windows.UI.Xaml.Controls {
public class AppBarButton : Button, ICommandBarElement, ICommandBarElement2 {
string KeyboardAcceleratorText { get; set; }
public static DependencyProperty KeyboardAcceleratorTextProperty { get; }
AppBarButtonTemplateSettings TemplateSettings { get; }
}
public class AppBarToggleButton : ToggleButton, ICommandBarElement, ICommandBarElement2 {
string KeyboardAcceleratorText { get; set; }
public static DependencyProperty KeyboardAcceleratorTextProperty { get; }
AppBarToggleButtonTemplateSettings TemplateSettings { get; }
}
public class MenuFlyoutItem : MenuFlyoutItemBase {
string KeyboardAcceleratorText { get; set; }
public static DependencyProperty KeyboardAcceleratorTextProperty { get; }
MenuFlyoutItemTemplateSettings TemplateSettings { get; }
}
public class NavigationView : ContentControl {
string PaneTitle { get; set; }
public static DependencyProperty PaneTitleProperty { get; }
event TypedEventHandler<NavigationView, object> PaneClosed;
event TypedEventHandler<NavigationView, NavigationViewPaneClosingEventArgs> PaneClosing;
event TypedEventHandler<NavigationView, object> PaneOpened;
event TypedEventHandler<NavigationView, object> PaneOpening;
}
public sealed class NavigationViewPaneClosingEventArgs
public enum WebViewPermissionType {
Screen = 5,
}
}
namespace Windows.UI.Xaml.Controls.Primitives {
public sealed class AppBarButtonTemplateSettings : DependencyObject
public sealed class AppBarToggleButtonTemplateSettings : DependencyObject
public sealed class MenuFlyoutItemTemplateSettings : DependencyObject
}
namespace Windows.UI.Xaml.Input {
public sealed class KeyboardAcceleratorInvokedEventArgs {
KeyboardAccelerator KeyboardAccelerator { get; }
}
public enum KeyboardAcceleratorPlacementMode

}

Visual Studio 2017 Update 4 makes it easy to modernize your desktop application and make it store ready

Last year with the Windows 10 Anniversary Update, we introduced the Desktop Bridge to provide desktop applications a path to modernize with the Universal Windows Platform, and to distribute via the Windows Store and the Microsoft Store for Business to all Windows 10 PCs, including devices that are running the Windows 10 S configuration.
The primary developer tool at the time was the Desktop App Converter, a tool that converts your current app installer into a Windows app package (.appx file), which can be submitted to the Windows Store or deployed via your distribution mechanism of choice. With Update 4 for Visual Studio 2017 we now have great support directly in Visual Studio for your Windows desktop application projects (WPF, Winforms, Win32, etc.). With the new tools you can now as you develop them in VS by simply hitting F5!
Let me walk you through an example, step-by-step. I am starting out with this Winforms app that showcases various chart controls. It’s been created several years ago in an older version of VS against .NET 4. Now my goal is to release it in the Windows Store and incrementally modernize it. Here is how easy it is now with Update 4 for Visual Studio 2017.

Step 1 – Add Windows App Packaging project to the solution
Before we start we need to make sure our desktop application project is loaded in Visual Studio 2017 and builds without error. Then in the next step we want to package our application as a Windows App Package (.appx file) so our Winforms app can take advantage of all the same Windows 10 app deployment features that are available to UWP apps: clean install & uninstall, seamless updates, Store distribution and many more. To do this, we will take advantage of the new tooling features introduced in Update 4 for Visual Studio 2017. We are adding a new project of type “Windows Application Packaging Project” to our solution:

Now we need to specify our min/target versions…

…and let the packaging  project know which project output to include in the package. To do so we right-click on the “Applications” node and set a reference to our Winforms project – done!

Important! Select the “DistributionPackage” project as your startup project. Now hit F5 and watch how your app gets packaged, deployed and launched as a Desktop Bridge app. You can start testing and debugging in this new execution context. If you set the Winforms project as startup project and hit F5, you can still test and debug the unpackaged version of your application
Step 2 – Configure app for Windows Store release
Our app is already running as a Desktop Bridge app now and we have successfully tested and debugged it in this configuration. Next we just need to put some finishing touches on the package so it integrates nicely with the Windows 10 Shell (tiles, badges, etc.) and to make sure it conforms to the Store submission requirements. First thing, we need to replace the default visual assets that come with the project template with our real, application-specific assets. This is very easy now in Visual Studio 2017 with the Visual Assets Manager in the package manifest editor:

To prepare for our Store submission we need to create the application in the Windows Dev Center and reserve our application name, provide screenshots for the store front, set the price, age ratings, etc. If you are not planning to distribute via the Windows Store, you can skip this step.

Last thing we need to do before we can release our app to the public is create a package bundle that is ready to deploy and Store-compliant. This bundle can contain binaries for different architectures, resources for different locales as well as the symbols for our binaries so we can later make sense of any crash reports in the Dev Center or Mobile Center. This can be done for Desktop Bridge apps directly from Visual Studio now, just like you would do for any UWP app:

As part of creating the packages we also run the certification tests and then submit the package to the Dev Center for certification and publishing. You can try the result of my submission out now and install the sample app on your machine from the Store by clicking on the badge below – source code for the app is available for your reference here.

What else does this enable for developers?
Aside from distributing and monetizing via Windows Store, your app now enjoys the modern deployment capabilities built into Windows 10. You don’t need to build an installer anymore, updates are automatic and differential. Uninstalls are guaranteed to be clean. Moreover, since your app is now in the Windows 10 App Model, you have access to UWP APIs and features, such as live tiles, Cortana integration, background tasks etc. Another important benefit specifically for Windows Forms apps is the new high DPI support in .NET 4.7, which is included in the Windows Creators Update (1703). Our sample app here is taking advantage of this new support, by following the steps outlined in this article.
And there is more
Talking about installers, did you know that your app package is also your installer on Windows 10? Users can just click to install it, as long as it’s signed with a certificate that is trusted on the target device. This enables you to distribute your modernized desktop application in the way that’s right for your scenario, without having to go through the Store – e.g. for LOB applications in an enterprise. Learn more about it here.

Conclusion
Getting your desktop application development project ready for Windows Store submission is easy now with Visual Studio 2017 Update 4. Once converted to a Windows App Package your app can take advantage of all the Windows 10 platform capabilities and start using new APIs and features on Windows 10. Here are some resources for more details:
Desktop Bridge docs
Desktop Bridge samples
App Modernization video on Channel 9
Are you ready to submit your desktop application to the Windows Store? Let us know about it here, and we will help you through the process!

New Map Control features in Windows 10 Fall Creators Update

The Maps team has been busy making improvements and adding new features to the Maps platform for the Windows 10 Fall Creators Update. In addition to performance and visual improvements to the 3D engine, we are introducing features requested by users, like the ability to import 3D models into the map and support for layering and binding for map elements. We also are making enhancements to the styling API to allow clients to specify base map styles and visual states for their own map elements. Finally, we are announcing a places API to see relevant information of a place right within the current context of the calling app.
Without further ado, please see the highlights below and keep your feedback coming!
3D Buildings
You might recall that some 3D buildings were missing in the previous release. We have been working hard since then to bring them back (and improve the ones that didn’t look correct) with this update.  Keep an eye out for more 3D buildings in the next few months!

3D Objects
We are adding a new MapElement called MapElement3D. Along with MapModel3D, this new API can be used to import and display 3D objects with ease. Think about fancy 3D push pins, cars, planes, etc.  The possibilities are endless!
Here are some great examples of MapElement3D displaying 3D models at a specific location, orientation and scale on the Windows 10 Map Control:
Avatars

Cars
Clouds
Map Layering APIs
We also are adding a new MapLayer class, the first derivation of which is MapElementsLayer. Unlike the existing MapControl.MapElements API, this can be used to manipulate groups of elements independently as a unit or to designate a joint purpose.
Bind your data to the map using MapControl.Layers
You can bind elements on the map to your own custom collections of business objects with the Map Control.Layers API.
See How To: Display points of interest (POI) on a map.
Map Styling APIs extensions
We are extending the current set of Map Styling APIs for Windows 10 Map Control. In the previous release, we added the MapStylesheet API to allow you to dynamically change the look and feel of the map in real-time. In this release, we are adding support for two new properties on MapElement: MapStyleSheetEntry and MapStyleSheetEntryState, which can be used to more deeply customize the appearance of your map elements using one of the default style entries and states or custom ones.
See How To: Customize Your Map Elements
Here are some examples of the customization that can be done of map elements using the new styling extensions on the Windows 10 Map Control:
Integrate your elements better with the base map using MapStyleSheetEntry
You can make your map elements look like they are part of the base map by setting their style to an existing entry in the map style sheet such as Water. See MapStyleSheetEntry for the full list of entries you can chose from.

Bing logo is rendered by the Windows 10 Map Control through changing the map polygon’s MapStyleSheetEntry property to Water.
Implement states on your map elements using MapStyleSheetEntryState
You can further modify the appearance of your map elements by leveraging default states like Hover and Selected in the map style sheet, or override them to create your own. See MapStyleSheetEntriesStates for the full list of states you can chose from.

Bellevue Square, City Center and Meydenbauer POIs are rendered by the Windows 10 Map Control through overriding the scale of the existing UserPoint entry and changing the map icon’s MapStyleSheetEntryState property to a custom state that extends the existing Hover and Selected entry states.
Place Info
Finally, we are happy to announce the new PlaceInfo API that allows you to see rich relevant information of a place without the need of switching context, in a pop-up UI, right within your own app.

https://github.com/Microsoft/Windows-universal-samples/tree/dev/Samples/MapControl
API Updates and Additions
For a list of the APIs added since Windows 10 Creators Update, please see here the following resources:
MapElement: MapStyleSheetEntry, MapStyleSheetEntryState and Tag properties
MapElement3D
MapElementsLayer
MapStyleSheetEntries
MapStyleSheetEntryStates
PlaceInfo
For more details on all new APIs go to MSDN.

The UWP Community Toolkit v2.0

Today, the UWP Community Toolkit graduates to version 2.0 and sets the stage for future releases.
There have been seven releases since the UWP Community Toolkit was first introduced exactly one year ago and version 2.0 is the first major and largest update to date. The developer community has worked enthusiastically to build something that is used by thousands of developers every month. Today, there are over 100 contributors, and developers have downloaded the packages over 250,000 times. This would not be possible without the strength of the community – Thank You!
For developers, and designers alike
Beginning with the v2.0 release, the UWP Community Toolkit is making efforts to align with the latest Windows 10 Fall Creators Update to enable developers to take advantage of the new APIs and the new Fluent Design System.
The Fluent Design System defines several foundational elements that will make new designs perform beautifully across devices, inputs and dimensions. To prepare for the general availability of the Fall Creators Update later this year, the community has committed to update all UWP Community Toolkit controls to adopt Fluent Design. Over the coming months, new and existing controls will be updated to support light, depth, material, motion and scale. The sample app will also be updated to take full advantage of the new foundational elements to demonstrate what is possible.

Updating the Sample App
The UWP Community Toolkit Sample App showcases toolkit features for developers by providing tools to get started using the toolkit in their apps, and it continues to get better. In the largest update since the initial release, developers can now edit XAML directly in the sample app and instantaneously view the results side by side. This is a very powerful addition that allows developers to get started with development immediately by simply downloading the app from the store.
But that’s not all. Taking inspiration from the Fall Creators Update, the sample app has been updated to use an improved and redesigned navigation model. The navigation has moved to the top and it’s now much easier to get to any sample. In addition, a new landing page has been added to make it easier to find what is new and keep track of favorite samples.

Beyond UWP
The UWP Community Toolkit has received feedback about the importance of supporting cross-platform development to enable developers to share more of their code across platforms. Version 2.0 introduces two new packages: Microsoft.Toolkit and Microsoft.Toolkit.Services with the commitment to support more cross platform APIs in future releases. These packages are built with .NET Standard and support any platform with .NET Standard 1.4 and above. The Bing Service is the first API to go cross-platform and there is currently work underway to move more services to the new packages.
What else is new?
As with every release, the community has worked together to share their ideas, build new controls and helpers libraries and improve the UWP Community Toolkit for everyone. This release is no different.
There are several large additions and updates to highlight here, but make sure to visit our release notes for all additions and improvements:
Added InAppNotification control – a control to show local notifications in app
Added TextToolbar control – text editing control that enables easy rich text and Markdown formatting
Updated Expander to support all orientations and added LayoutTranformControl from the WinRT XAML Toolkit
Updated Menu to support underline characters, orientation and many other improvements
This is just the start
We learned a lot in the past year, and the community has worked together to make toolkit APIs as easy and flexible as possible. Few APIs and packages have been restructured to make them more convenient for developers and allowed more flexibility for future additions and updates. For example, the Microsoft.Toolkit.UWP.Connectivity package was added to unify all connectivity APIs such as Bluetooth and networking. Likewise, all extensions and helpers are now unified under a single namespace and are consistent across API.
As a reminder, although most of the development efforts and usage of the UWP Community Toolkit is for Desktop apps, it also works great on Xbox One, Mobile, HoloLens, IoT and Surface Hub devices. You can get started by following this tutorial, or preview the latest features by installing the UWP Community Toolkit Sample App from the Windows Store.
If you would like to contribute, please join us on GitHub! To join the conversation on Twitter, use the #uwptoolkit hashtag.

Windows 10 SDK Preview Build 16267 and Mobile Emulator Build 15240 Released

Today, we released a new Windows 10 Preview Build of the SDK and the Mobile Emulator to be used in conjunction with Windows 10 Insider Preview (Build 16267 or greater). The Preview SDK Build 16267 contains bug fixes and under development changes to the API surface area.
The Preview SDK and Mobile Emulator can be downloaded from developer section on Windows Insider.
For feedback and updates to the known issues, please see the developer forum. For new developer feature requests, head over to our Windows Platform UserVoice.
Things to note:
This build works in conjunction with previously released SDKs and Visual Studio 2017. You can install this SDK and still continue to submit your apps that target Windows 10 Creators build or earlier to the Windows Store.
The Windows SDK will now formally only be supported by Visual Studio 2017 and greater. You can download the Visual Studio 2017 here.
Known Issues
Compilation fails on non-Windows 10 platformsWhen building apps on previous platforms, you may get a build error:
C:program files (x86)Windows Kits10bin10.0.16232.0x86genxbf.dll:C:program files (x860Windows Kits10bin10.0.16232.0x86genxbf.dll(0,0): Error WMC0621: Cannot resolve ‘GenXbf.dll’ under path ‘C:program files (x860Windows Kits10bin10.0.16232.0x86genxbf.dll’.  Please install the latest version of the Windows 10 Software Development Kit.
Process ‘msbuild.exe’ exited with code ‘1’.
This will occur if the minimum target platform version is set to 10.0.16225.0. To work around this, right click on your project file and choose properties or open your project file in your favorite editor, and change the version to a previous released SDK. For example:

&lt;WindowsTargetPlatformMinVersion&gt;10.0.10586.0&lt;/WindowsTargetPlatformMinVersion&gt;

Breaking Changes
ecmangen.exe removal from the SDK: Ecmangen.exe will no longer ship with the Windows SDK. Developers who rely on ecmangen for event manifest creation are advised to install the Windows Creators Edition of the SDK to obtain the file. Developers may also use notepad or other XML editor of choice for manifest creation. A schema file is available on MSDN to aid in manifest creation, for tools that support it.
API Updates and Additions
When targeting new APIs, consider writing your app to be adaptive in order to run correctly on the widest number of Windows 10 devices. Please see Dynamically detecting features with API contracts (10 by 10) for more information.
The following are the API changes since the 16257 Preview SDK, please reference that list.
Additions to Preview SDK 16257

 
namespace Windows.Storage.Provider {
public enum HardlinkPolicy : uint
public enum HydrationPolicy {
AlwaysFull = 3,
Partial = 0,
}
public enum InSyncPolicy : uint {
DirectoryLastWriteTime = (uint)512,
FileLastWriteTime = (uint)256,
}
public enum PopulationPolicy {
AlwaysFull = 2,
}
public sealed class StorageProviderSyncRootInfo {
HardlinkPolicy HardlinkPolicy { get; set; }
}
}
namespace Windows.UI.WebUI {
public sealed class WebUIStartupTaskActivatedEventArgs : IActivatedEventArgs, IActivatedEventArgsDeferral, IActivatedEventArgsWithUser, IStartupTaskActivatedEventArgs {
ActivatedOperation ActivatedOperation { get; }
}
}

Removals from Preview SDK 16257

 
namespace Windows.Storage.Provider {
public enum HydrationPolicy {
NoPartial = 3,
OnDemand = 0,
}
public enum PopulationPolicy {
NoPartial = 2,
}
}

New Tools in Windows Device Portal for the Windows 10 Fall Creators Update

In the Windows 10 Fall Creators Update, Device Portal now offers several new tools from across Windows to help you location test your UWP, explore Mixed Reality, build new hardware peripherals and test your apps new installation pipeline. It’s a little bit of goodness for everyone, and we’re excited to share these with you.
If you’re not familiar with Device Portal, you can check out the blog posts below to see what other tools you can find in Device Portal, or look at the new docs.microsoft.com to learn how to enable it.
And as always, all of these tools are backed by a REST API, so that you can use it from a scripting or client application environment using the Device Portal Wrapper.
Location Based Testing
Most of us don’t have the travel budgets to test our apps across the world – but pretending to travel is almost as good!  The Location tool in Device Portal lets you easily change the location that Windows reports to apps. By tapping the “Override” check box, you can swap out the device location for whatever you set using the map or lat/long text boxes. Be sure to uncheck the box when you’re done so that your location (and timezone) come back to reality – every vacation must end…

Figure 1: The News app keeping me up to date with local headlines!
This also works for web pages in Microsoft Edge, letting you test your webpages in different parts of the world.
Some notes on what this tool can and cannot do:
This doesn’t change the locale of your PC! So the News app above still saw an EN-US user in the middle of Italy.
You may not see all apps using this location. Some programs don’t use the Windows API to determine location or have special logic (e.g. using your IP address) to determine your location.
This tool marks the PositionSource of the location data as “Default.” Some apps may check for the source and alter their behavior based on it.
Happy travels!
USB Diagnostics
This one goes out to all the hardware folks – if “HLK” or “WDK” sound familiar, you might find this handy. The USB team has updated the USBView tool to work inside Device Portal, so developers working on new hardware can have more tooling at their fingertips.
The USB Devices tool can be a bit tricky to find – head to the hamburger menu in the top right, and go to “Add tools to workspace.”  Scroll to the bottom and check the “USB Devices” box, then hit “Add.” And voila – a full view of your systems USB hubs, controllers and peripherals. The hubs and controllers expand to show individual devices using the + (plus) sign, and clicking the gear will expand to show the items properties.

Streaming App Install Debugging
The Windows 10 Creators Update added ““streaming installation” for UWP, which allows a user to launch the app before it finished downloading. In order to make this easy to test, the App Model team has added a Streaming Install Debugger tool to Device Portal. To use it, deploy an app with content groups to the device, then open the Streaming Install Debugger. In it you’ll be able to edit the states of the content groups so you can test your apps behavior as streaming install is being simulated and ensure it behaves correctly when content groups are missing.

For more details, check out Andy Liu’s blog posts about the new App Installer and Streaming Install Debugger tools.
Mixed Reality Tooling
One of the bigger splashes in the Fall Creators Update is the addition of Mixed Reality to Windows Desktop. As part of that release, we’re including a suite of tools to help developers build great Mixed Reality apps. Two of these tools may look familiar to HoloLens developers – 3D View and a Framerate counter. There’s also a new app launch option that appears when you have an immersive headset attached to your PC, which lets you launch your app in Mixed Reality.
Frame rate is an important factor in making mixed reality apps comfortable, and it’s important for developers to optimize performance to hit full frame rate on the systems they support. The Frame Rate tool in the Device Portal helps by showing developers both the frame rate of their app and of the system’s compositor.

The 3D View helps when testing your immersive headset’s interactions with the real world, displaying its position as it moves through space.

Finally, what good is tooling if you can’t actually run your app in your immersive headset? Now, when you have an immersive headset attached, the Installed Apps tool will add a button letting you launch the app in the HMD. While fully immersive apps will always run in Mixed Reality, this new button is particularly useful for 2D UWP apps (or apps that switch between 2D and immersive) when you want to test them in Mixed Reality.

As always, if you have ideas for Device Portal that would help you write or debug apps, please leave us a note on our UserVoice or upvote an existing request. If you run into bugs, please file it with us via the Feedback Hub.
Related Posts:
Using Device Portal to view debug logs for UWP
Using the App File Explorer to see your app data

Creating Materials and Lights in the Visual Layer

In today’s post, we’re going wrap up this series by combining everything we’ve learned so far and take you through the steps in creating a custom material. We also have an amazing new tool to show you that empowers anyone to design a custom material. To see how you can use these custom materials in your XAML app, be sure to check out the last two posts in this series; XAML and Visual Layer Interop, part one and part two.

The Fluent Design Language is an evolving concept, rather than a one-time design language release like MDL and MDL2. It was designed to expand and grow as Microsoft and the community of creators (developers and designers), adds to what it could be. We’ll show you that anything is possible, as designers, developers and the Windows community have common ground to share their creations and create amazing materials.
Let’s get started by first showing you how a material is created by chaining effects, then we’ll explore using the new Material Creator to easily and quickly create materials.
Creating Material with the Visual Layer
CompositionEffectBrush
Whether we’ll be using the effect in a XamlCompositionBrushBase or painting a SpriteVisual, the construction of the effect graph is the core of the approach. In order to create the material we want, we’ll need the following components:
Effect sources: A SurfaceBrush for the NormalMap and a BackdropBrush for access to the pixels underneath the material
The effect graph: A composite of different effects to control the Material’s reflectance properties and filter effects (such as blur and tint) to customize for UI usage
Lighting: The Visual is in a scene that has a CompositionLight applied
Let’s start with the first source, a SurfaceBrush. This will be provided by using LoadedImageSurface to load a NormalMap.
NormalMap and LoadedImageSurface

If you’ve had any experience with 3D computer graphics, maybe as a game developer, you may already know what a normal map is and the image above looks familiar. If you’ve never worked with one before, Normal mapping is a technique that determines the reflectance of light at every pixel (read more about Normal mapping here). The Visual Layer in Windows 10 gives you a choice of industry standard reflectance models; Blinn-Phong and Physically Based Blinn-Phong. Go here to read more about the math behind how this is done.
For today’s demo, we used a 2D picture of a textured surface and transformed it into a Normal map image using an image editor. There are many image editing tools that let you do this. You can use any one you prefer to create your image.
To get started, we can load the image using the new LoadedImageSurface API. Let’s add a private field for the LoadedImageSurface, load the image and create a CompositionSurfaceBrush with it.

// Load NormalMap onto an ICompositionSurface using LoadedImageSurface
LoadedImageSurface _surface = LoadedImageSurface.StartLoadFromUri(new Uri(&quot;ms-appx:///Images/NormalMap.jpg&quot;), new Size(512,384));

// Load Surface onto SurfaceBrush
CompositionSurfaceBrush normalMap = compositor.CreateSurfaceBrush(_surface);
normalMap.Stretch = CompositionStretch.Uniform;

Now we’re ready to move on to creating and chaining effects.
Chaining Effects to create the effect graph
For our material, we are going to create a chain of effects that leverages the Win2D’s ArithmeticCompositeEffect (note: be sure to add the Win2D NuGet package to your project). All effects can be used as input sources for other effects, thus enabling you to allow a chain of effects to one or more inputs.
ArithmeticCompositeEffect lets you assign two sources for the composite, giving each one a weight toward the final effect. For example, Source1 at 0.75 (75%) and Source2 at 0.25 (25%). You can also use an additional ArithmeticCompositeEffect as one of the sources to add more effects in the composite chain.
Let’s step back for a minute and think about how we want create the composite:
Parent ArithmeticCompositeEffect to be used for Brush
Source 1: Child ArithmeticCompositeEffect
Source 1: ColorSourceEffect for tint coloring
Source 2: GaussianBlurEffect using the BackDropBrush for its source

Source2: SceneLightingEffect using the Normal map for its source

For source 1, we’ll combine a ColorSourceEffect and GaussianBlurEffect (from Win2D) with a nested ArithmeticSourceEffect. For Source 2, we’ll use a SceneLightingEffect (from Windows.UI.Composition.Effects). This will manipulate the reflective properties of the effect’s source when a CompositionLight, from a XamlLight for example, is applied.
Note that the SceneLightingEffect is used to modify the default lighting applied to the contents of a SpriteVisual targeted by a CompositionLight. In today’s example, we are going to create SurfaceBrush using a NormalMap (loaded by LoadedImageSurface) to define dents and bumps that the light reflects off of.
Furthermore, in order to use the SceneLightingEffect, the content being modified must be defined as one of the sources into a multi-input effect graph, with the other input being the SceneLightingEffect. For example, above, the content whose lighting properties are being modified is defined by Source1 of the parent ArithmeticCompositeEffect.
Here’s what the code looks like for the effect graph:

// Define Effect graph
const float glassLightAmount = 0.5f;
const float glassBlurAmount = 0.95f;
Color tintColor = Color.FromArgb(255, 128, 128, 128);

var graphicsEffect = new ArithmeticCompositeEffect
{
Name = &quot;LightComposite&quot;,
Source1Amount = 1,
Source2Amount = glassLightAmount,
MultiplyAmount = 0,
// Nested Composite to combine the Blur and Color tint effects
Source1 = new ArithmeticCompositeEffect
{
Name = &quot;BlurComposite&quot;,
Source1Amount = 1 – glassBlurAmount,
Source2Amount = glassBlurAmount,
MultiplyAmount = 0,
Source1 = new ColorSourceEffect
{
Name = &quot;Tint&quot;,
Color = tintColor,
},
Source2 = new GaussianBlurEffect
{
BlurAmount = 20,
Source = new CompositionEffectSourceParameter(&quot;Backdrop&quot;),
Optimization = EffectOptimization.Balanced,
BorderMode = EffectBorderMode.Hard,
},
},
// The SceneLighting effect, which will use a NormalMap
Source2 = new SceneLightingEffect
{
AmbientAmount = 0.15f,
DiffuseAmount = 1,
SpecularAmount = 0.1f,
NormalMapSource = new CompositionEffectSourceParameter(&quot;NormalMap&quot;)
}
};

Notice the SceneLightingEffect’s NormalMapSource property and the GaussianBlurEffect’s Source; these are parameter provided sources. We will set what these parameters are as we pull everything together to create the CompositionEffectBrush:

// Create EffectFactory and the CompositionEffectBrush
CompositionEffectFactory effectFactory = Window.Current.Compositor.CreateEffectFactory(graphicsEffect);
CompositionEffectBrush effectBrush = effectFactory.CreateBrush();

// Create BackdropBrush, this is used by the GaussianBlurEffect
CompositionBackdropBrush backdrop = Window.Current.Compositor.CreateBackdropBrush();

// Set Sources to Effect
effectBrush.SetSourceParameter(&quot;NormalMap&quot;, _normalMap);
effectBrush.SetSourceParameter(&quot;Backdrop&quot;, backdrop);

With the CompositionEffect completed, we can now use it to paint a SpriteVisual, like this:

SpriteVisual spriteVisual = Window.Current.Compositor.CreateSpriteVisual();
spriteVisual.Brush = effectBrush;

If you’re primarily a XAML dev, you can use this effect in a XamlCompositionBrushBase. Let’s take a look.
Using the CompositionEffectBrush in a XamlCompositionBrushBase
As I mentioned earlier, we can also create this effect graph in XamlCompositionBrushBase and set the XamlCompositionBrushBase’s CompsositionBrush property. If you haven’t read the post in this series on how to create a XamlCompositionBrushBase, go here to catch up.
As with the other XamlCompositionBrushBase implementations, we build the effect graph in the OnConnected method and make sure that the user’s device supports effects. This can be done using the AreEffectsSupported method of the CompositionCapabilities API.
Here’s the full class:

public sealed class MaterialBrush : XamlCompositionBrushBase
{
private LoadedImageSurface _surface;

protected override void OnConnected()
{
if (DesignMode.DesignModeEnabled) return;

Compositor compositor = Window.Current.Compositor;

// CompositionCapabilities: Are Effects supported?
bool usingFallback = !CompositionCapabilities.GetForCurrentView().AreEffectsSupported();
FallbackColor = Color.FromArgb(100, 60, 60, 60);

if (usingFallback)
{
// If Effects are not supported, use Fallback Solid Color
CompositionBrush = compositor.CreateColorBrush(FallbackColor);
return;
}

// Load NormalMap onto an ICompositionSurface using LoadedImageSurface
_surface = LoadedImageSurface.StartLoadFromUri(new Uri(&quot;ms-appx:///Images/NormalMap.jpg&quot;), new Size(512, 384));

// Load Surface onto SurfaceBrush
CompositionSurfaceBrush normalMap = compositor.CreateSurfaceBrush(_surface);
normalMap.Stretch = CompositionStretch.Uniform;

// Define Effect graph
const float glassLightAmount = 0.5f;
const float glassBlurAmount = 0.95f;
Color tintColor = Color.FromArgb(255, 128, 128, 128);

var graphicsEffect = new ArithmeticCompositeEffect()
{
Name = &quot;LightComposite&quot;,
Source1Amount = 1,
Source2Amount = glassLightAmount,
MultiplyAmount = 0,
Source1 = new ArithmeticCompositeEffect()
{
Name = &quot;BlurComposite&quot;,
Source1Amount = 1 – glassBlurAmount,
Source2Amount = glassBlurAmount,
MultiplyAmount = 0,
Source1 = new ColorSourceEffect()
{
Name = &quot;Tint&quot;,
Color = tintColor,
},
Source2 = new GaussianBlurEffect()
{
BlurAmount = 20,
Source = new CompositionEffectSourceParameter(&quot;Backdrop&quot;),
Optimization = EffectOptimization.Balanced,
BorderMode = EffectBorderMode.Hard,
},
},
Source2 = new SceneLightingEffect()
{
AmbientAmount = 0.15f,
DiffuseAmount = 1,
SpecularAmount = 0.1f,
NormalMapSource = new CompositionEffectSourceParameter(&quot;NormalMap&quot;)
},
};

// Create EffectFactory and EffectBrush
CompositionEffectFactory effectFactory = compositor.CreateEffectFactory(graphicsEffect);
CompositionEffectBrush effectBrush = effectFactory.CreateBrush();

// Create BackdropBrush
CompositionBackdropBrush backdrop = compositor.CreateBackdropBrush();

// Set Sources to Effect
effectBrush.SetSourceParameter(&quot;NormalMap&quot;, normalMap);
effectBrush.SetSourceParameter(&quot;Backdrop&quot;, backdrop);

// Set EffectBrush as the brush that XamlCompBrushBase paints onto Xaml UIElement
CompositionBrush = effectBrush;
}

protected override void OnDisconnected()
{
// Clean up resources
_surface?.Dispose();
_surface = null;

CompositionBrush?.Dispose();
CompositionBrush = null;
}
}

To see this in action, let’s create a Grid to put in the middle of our page’s root Grid and set an instance of our MaterialBrush to that Grid’s Background brush:

&lt;Grid Background=&quot;Gray&quot;&gt;
&lt;Grid Width=&quot;580&quot;
Height=&quot;387&quot;
HorizontalAlignment=&quot;Center&quot;
VerticalAlignment=&quot;Center&quot;&gt;

&lt;!– Our new MaterialBrush –&gt;
&lt;Grid.Background&gt;
&lt;brushes:MaterialBrush /&gt;
&lt;/Grid.Background&gt;
&lt;/Grid&gt;
&lt;/Grid&gt;

Here’s what it would look like if you ran the app now:

This is because you’re missing the second part of the approach, the lighting!
Illuminating the Material with Lights
In the last post, we created two lights (an AmbientLight “AmbLight” and the SpotLight “HoverLight”). We’ll use them today to apply lighting to the UIElement that is using our custom material.
Since our MaterialBrush uses the new SceneLightingEffect with a Normal map, any lights applied will enhance the material per the SceneLightingEffect’s configuration. Note that this isn’t necessary, but can greatly enhance your material. For example, if you’re using an Acrylic material in your app, adding Reveal will enhance the Acrylic.
Let’s now add the two XamlLights to the Grid:

&lt;Grid Background=&quot;Gray&quot;&gt;
&lt;Grid Width=&quot;580&quot;
Height=&quot;387&quot;
HorizontalAlignment=&quot;Center&quot;
VerticalAlignment=&quot;Center&quot;&gt;
&lt;Grid.Background&gt;
&lt;brushes:MaterialBrush /&gt;
&lt;/Grid.Background&gt;

&lt;!– Added lights –&gt;
&lt;Grid.Lights&gt;
&lt;lights:HoverLight /&gt;
&lt;lights:AmbLight /&gt;
&lt;/Grid.Lights&gt;
&lt;/Grid&gt;
&lt;/Grid&gt;

Now, this is what you’ll see at runtime:

What if it were easier to create and experiment with new materials? What if there were a tool that anyone can use? Let’s take a look at what’s coming to the WindowsUIDevLabs GitHub repo, the Material Creator tool.
Using the new Material Creator
Introducing availability of the new Material Creator tool!

Creating custom materials may sometimes requires a bit of experimentation and tweaking to get the effect’s property configuration just right. This would take time if you had to constantly tweak and redeploy your app. What if there were a way that you could change effect properties and material layers in real time?
The Material Creator can be found on the WindowsUIDevLabs GitHub repo in the demos folder here. (Note: you need to be running Windows 10, build 16225 or higher to use the Material Creator).
Generating the SceneLightingEffect code

One of the great features of the tool is being able to see the effect graph after you’re done creating the material. Click the ellipsis next to the save button and select “view effect graph” to see the C# code for the SceneLightingEffect. You can then copy and use this code directly in your custom material class.
If you go back up to the part of this article where we created the ArithemticCompositeEffect that contains a SceneLightingEffect, that’s where you can use this code!
Saving and Loading Materials
The Material Editor can also save and load materials! If you want to save your current progress on a material, or share a completed material with another developer, just click the Save button and it will create a json file containing all the layers and effect configurations. To load an existing material or edit a material shared with you, just click Load and select the json file.
The key takeaway is that you don’t need to be a developer to create materials. A designer can create a material and then share the saved json file with a developer for implementation in a XamlCompositionBrushBase. Even Windows enthusiasts, like the Windows Insiders, can start building out a universe of materials to drive the evolution of Fluent Design.
Blog Series Wrap up: The future of Fluent Design materials
Acrylic and Reveal are stunning examples of how using Material with Lights can alter the Windows experience, but they’re just the beginning of what is possible. The vision for the Fluent Design Language going forward is that developers and designers can easily build custom materials, innovate and share as well.
The message we want you to walk away with is that you can build new Materials, for a couple primary reasons:
Because you’re a Creator
Because it embodies your brand
We look forward to seeing what kinds of materials you create for your Windows apps! If you’ve already built your own material, feel free to share in the comments below.
Resources
Demo Code:
Material Creator
Brush Interop
Light Interop

Blog posts: XAML and Visual Layer Interop series
Part One
Part Two

Lighting Overview
CompositionCapabilities API
Light Types
Mathematics of lighting
SceneLightingEffect
WindowsUIDevLabs GitHub repo (contains Samples Gallery app)
Win2D Effects API Documentation

Powered by WPeMatico