DebugSettings DebugSettings DebugSettings Class

Declares how certain aspects of the app behave when it is run in a debug environment

Syntax

Declaration

public sealed class DebugSettingspublic sealed class DebugSettingsPublic NotInheritable Class DebugSettings

Remarks

This class can't be constructed. Get the value from DebugSettings and then change the properties as necessary.

OnLaunched(LaunchActivatedEventArgs) is a good place to change DebugSettings values.

Not all modes enabled by DebugSettings require that a debugger is attached. For example, the frame-rate counter associated with EnableFrameRateCounter will appear in an app that runs with that setting even if you activate it as a tile without the debugger.

Don't leave any DebugSettings properties explicitly set in your production code.

Examples

This example shows an OnLaunched(LaunchActivatedEventArgs) override that accesses DebugSettings and sets two properties of the singleton DebugSettings value to true. The context of this code is the app.xaml code-behind, so this refers to the created Application object for the app.

protected override void OnLaunched(LaunchActivatedEventArgs args) {
    this.DebugSettings.EnableFrameRateCounter = true;
    this.DebugSettings.IsOverdrawHeatMapEnabled = true;
    //...
}

Properties summary

Gets or sets a value that indicates whether to display frame-rate and per-frame CPU usage info. These display as an overlay of counters in the window chrome while the app runs.

Gets or sets a value that indicates whether to highlight areas of the app UI surface that are being redrawn each frame.

Gets or sets a value that indicates whether to engage the binding tracing feature of Microsoft Visual Studio when the app runs.

Gets or sets a value that enables a debug setting that visualizes overdraw operations. This visualization is useful during application development for detecting layout, animation, and other operations that are graphics processing intensive.

Gets or sets a value that indicates whether to engage the text performance visualization feature of Microsoft Visual Studio when the app runs.

Events summary

Occurs when a Binding cannot be resolved.

Properties

  • EnableFrameRateCounter
    EnableFrameRateCounter
    EnableFrameRateCounter
    EnableFrameRateCounter

    Gets or sets a value that indicates whether to display frame-rate and per-frame CPU usage info. These display as an overlay of counters in the window chrome while the app runs.

    public bool EnableFrameRateCounter { get; set; }public bool EnableFrameRateCounter { get; set; }Public ReadWrite Property EnableFrameRateCounter As boolpublic bool EnableFrameRateCounter { get; set; }

    Property Value

    • bool
      bool
      bool

      true to display the overlay debug counters; otherwise, false.

    Remarks

    The overlay debug counters have two sets of numbers. The set that appears on the upper left of the screen applies to just your app. The set that appears on the upper right applies to the system overall, and is also accounting for other apps that are drawing to the composited desktop. The right-side counter comes from the Microsoft DirectComposition components that are handling compositing for Microsoft Windows in general. Basically, if you set EnableFrameRateCounter to true, this also calls IDCompositionDeviceDebug::EnableDebugCounters in the underlying components. The result is that both the counters specific to apps using XAML and the Microsoft DirectComposition counters for all apps appear when you debug your Windows Store app.

    The format for the frame-rate counter displayed in the window chrome is:

    000000000000
    App fpsApp CPUSys fpsSys CPU

    • **App fps: ** The app's UI thread frame rate, in frames per second.
    • **App CPU: ** The CPU usage of the app's UI thread per frame, in milliseconds.
    • **Sys fps: ** The system-wide composition engine frame rate, in frames per second. This is typically pegged to 60.
    • **Sys CPU: ** The system-wide overall CPU usage of the composition thread per frame, in milliseconds.

    The App fps value is specifically reporting on the UI thread. There could be a much higher apparent refresh rate happening in your app that's related to the composition thread, but not to the UI thread. For more info on what each thread is responsible for, see Performance best practices for .

    OnLaunched(LaunchActivatedEventArgs) is a good place to change DebugSettings values. Another possibility is the App() constructor.

    Windows 8 behavior

    In Windows 8, the counters used a different format and didn't incorporate the Microsoft DirectComposition counters. That format was:

    000000000000000000000
    Comp fpsUI fpsMemoryBatchComp msUI ms
    • Comp fps: the frame rate for the composition thread
    • UI fps: the frame rate for the UI thread
    • Memory: memory utilization for textures
    • Batch: the count of surfaces that are sent to the graphics processing unit (GPU)
    • Comp ms: time in milliseconds per frame spent on the composition thread
    • UI ms: time in milliseconds per frame spent on the UI thread
  • EnableRedrawRegions
    EnableRedrawRegions
    EnableRedrawRegions
    EnableRedrawRegions

    Gets or sets a value that indicates whether to highlight areas of the app UI surface that are being redrawn each frame.

    public bool EnableRedrawRegions { get; set; }public bool EnableRedrawRegions { get; set; }Public ReadWrite Property EnableRedrawRegions As boolpublic bool EnableRedrawRegions { get; set; }

    Property Value

    • bool
      bool
      bool

      true to highlight redraw regions. false to not highlight redraw regions. The default is false.

  • IsBindingTracingEnabled
    IsBindingTracingEnabled
    IsBindingTracingEnabled
    IsBindingTracingEnabled

    Gets or sets a value that indicates whether to engage the binding tracing feature of Microsoft Visual Studio when the app runs.

    public bool IsBindingTracingEnabled { get; set; }public bool IsBindingTracingEnabled { get; set; }Public ReadWrite Property IsBindingTracingEnabled As boolpublic bool IsBindingTracingEnabled { get; set; }

    Property Value

    • bool
      bool
      bool

      true to engage the binding tracing feature of Microsoft Visual Studio; otherwise, false.

    Remarks

    This property is true by default, but for binding tracing to work, you must also select Mixed debugger type in Microsoft Visual Studio on the Debug page of the project designer.

    When binding tracing is enabled and you run your app with the debugger attached, any binding errors appear in the Output window in Microsoft Visual Studio.

  • IsOverdrawHeatMapEnabled
    IsOverdrawHeatMapEnabled
    IsOverdrawHeatMapEnabled
    IsOverdrawHeatMapEnabled

    Gets or sets a value that enables a debug setting that visualizes overdraw operations. This visualization is useful during application development for detecting layout, animation, and other operations that are graphics processing intensive.

    public bool IsOverdrawHeatMapEnabled { get; set; }public bool IsOverdrawHeatMapEnabled { get; set; }Public ReadWrite Property IsOverdrawHeatMapEnabled As boolpublic bool IsOverdrawHeatMapEnabled { get; set; }

    Property Value

    • bool
      bool
      bool

      true to enable the visualization, otherwise, false.

    Remarks

    Use this property as a debugging aid to visibly detect areas of the UI where applying a CacheMode for textures might be useful. For more info, see "Cache static content" section of Optimize your XAML markup.

    OnLaunched(LaunchActivatedEventArgs) is a good place to change DebugSettings values.

  • IsTextPerformanceVisualizationEnabled
    IsTextPerformanceVisualizationEnabled
    IsTextPerformanceVisualizationEnabled
    IsTextPerformanceVisualizationEnabled

    Gets or sets a value that indicates whether to engage the text performance visualization feature of Microsoft Visual Studio when the app runs.

    public bool IsTextPerformanceVisualizationEnabled { get; set; }public bool IsTextPerformanceVisualizationEnabled { get; set; }Public ReadWrite Property IsTextPerformanceVisualizationEnabled As boolpublic bool IsTextPerformanceVisualizationEnabled { get; set; }

    Property Value

    • bool
      bool
      bool

      true to engage the text performance visualization feature of Microsoft Visual Studio; otherwise, false.

Events

  • BindingFailed
    BindingFailed
    BindingFailed
    BindingFailed

    Occurs when a Binding cannot be resolved.

    public event BindingFailedEventHandler BindingFailedpublic event BindingFailedEventHandler BindingFailedPublic Event BindingFailedpublic event BindingFailedEventHandler BindingFailed

    Remarks

    IsBindingTracingEnabled must be true and there must be a debugger attached to the app process in order for BindingFailed to fire and for tracing to appear in debugger output. You don't need to handle the event in order to see tracing appear in a debugger. The debugger output contains message information that goes to the Output window of the debugger. Attaching a BindingFailed handler yourself is an advanced scenario for when you want to see the raw message.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.dll