Windows Presentation Foundation (WPF)

Windows Presentation Foundation (WPF) is a UI framework designed for building Windows desktop applications. It features a vector-based rendering engine that supports high DPI scaling and a flexible hosting model.

Key features include:

• Declarative Programming: Uses Extensible Application Markup Language (XAML) for UI definition.
• Application Model: Supports resources, controls, graphics, layout, and data binding.
• Platform Support: As of .NET 6.0, WPF supports ARM64.
• Target Platform: WPF applications run exclusively on Windows and are part of the Microsoft.NET.Sdk.WindowsDesktop SDK.

The WPF modernization strategy focuses on long-term investments to align with modern .NET standards and Windows design languages. Key areas of development include:

• Windows 11 Theming: Updating WPF control styles to support Windows 11 visual elements like rounded corners, snap layouts, and modern color schemes.
• Nullability Annotations: Enabling nullability annotations across the WPF codebase to improve code quality and reduce ArgumentNullException and NullReferenceException errors for consuming applications.
• Modern .NET Support: Long-term goals include support for trimming, NativeAOT, DirectX upgrades, and integration of newer .NET abstractions.
• Performance & Accessibility: Ongoing efforts to reduce memory usage, improve startup times, optimize rendering, and address high-priority accessibility bugs to ensure inclusive application experiences.

Some WPF assemblies contain circular dependencies where Assembly A uses types from Assembly B, and Assembly B uses types from Assembly A. To resolve this and allow compilation, WPF uses cycle-breaking assemblies. These assemblies re-define problematic types without full implementations or closures, allowing projects to reference them to break the dependency cycle.

There are two categories of cycle breakers:

1. Implementation cycle breakers: Used when a project needs to use types from a cycled assembly within its implementation. These typically include types and their closures to support usage from the calling assembly.
2. API cycle breakers: Used when an assembly is referenced from a ref-assembly or an implementation cycle breaker. These are minimal in footprint and generally avoid type closures as much as possible.

The following WPF project templates are provided for creating new projects using the dotnet new CLI tool:

• WPF Application (C#)
• WPF Application (VB)
• WPF Class library (C#)
• WPF Class library (VB)
• WPF Custom Control library (C#)
• WPF Custom Control library (VB)
• WPF User Control Library (C#)
• WPF User Control Library (VB)

The WPF repository produces two primary types of packages:

1. Microsoft.DotNet.Wpf.Github: A transport package containing assemblies and corresponding reference binaries built from this repository.
2. Microsoft.DotNet.Arcade.Wpf.Sdk: An MSBuild SDK that extends Microsoft.DotNet.Arcade.Sdk. It contains the build props, targets, and scripts required to build WPF. This SDK is built in this repository and consumed in other repositories to facilitate the split build process.

To ensure runtime availability and avoid version conflicts with other applications, WPF redistributes specific C++ dependencies under renamed identifiers. When deploying WPF applications on .NET Core, these renamed assemblies are bundled with the WPF runtime.

The following standard assemblies are renamed for WPF usage:

• vcruntime140.dll is renamed to vcruntime140_cor3.dll (Note: vcruntime140d.dll is used in Debug mode).
• d3dcompiler_47.dll is renamed to d3dcompiler_47_cor3.dll.

These renames allow WPF to function without requiring users to manually install VC runtime redistributables or D3D compiler packages, while preventing clashes with applications that might require different versions of the original filenames.

To test your application against a specific version of the Microsoft.WindowsDesktop.App shared runtime when building from source, add the following to your project file:

1. Define a MicrosoftWindowsDesktopAppVersion property.
2. Update the Microsoft.WindowsDesktop.App FrameworkReference to use that version as the TargetingPackVersion.

<PropertyGroup>
    <MicrosoftWindowsDesktopAppVersion>3.0.0-preview5-27619-18</MicrosoftWindowsDesktopAppVersion>
</PropertyGroup>

<ItemGroup>
    <FrameworkReference Update="Microsoft.WindowsDesktop.App">
        <TargetingPackVersion>$(MicrosoftWindowsDesktopAppVersion)</TargetingPackVersion>
    </FrameworkReference>
</ItemGroup>

After building, you must copy the generated artifacts to your local .NET installation to test changes in Visual Studio.

Note: It is recommended to use a script to automate these copies.

1. Runtime Files: Copy from .\artifacts\packaging\Debug\x64\Microsoft.DotNet.Wpf.GitHub.Debug\lib\net6.0\* to your local shared framework directory (e.g., ..\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App\<version>\).
2. Reference Files: Copy from .\artifacts\packaging\Debug\x64\Microsoft.DotNet.Wpf.GitHub.Debug\ref\net6.0\* to your local reference packs (e.g., ..\Program Files\dotnet\packs\Microsoft.WindowsDesktop.App.Ref\<version>\ref\net6.0\).

When configuring WPF solutions that contain both managed and native projects, ensure that the solution-to-project configuration mappings follow these rules to maintain consistency:

• For Native Projects: Map the AnyCPU solution configuration to the x86 project configuration.
• For Managed Projects: Map the x86 solution configuration to the AnyCPU project configuration.
• Official Builds: Always specify x86 or x64 solution configurations explicitly. The AnyCPU solution configuration is intended for developer builds only.

Use the Solution -> Properties -> Configuration view in your IDE to verify that the mapping between solution-configuration and project configuration is consistent for every possible configuration.

When the Fluent theme is enabled in WPF, it automatically attempts to apply a Mica (DWMSBT_MAINWINDOW) backdrop by interacting with the Desktop Window Manager (DWM). If you need to prevent this behavior, you can disable the application of the backdrop using an app-context switch.

You can disable the backdrop using either a project file configuration or a runtime configuration file.

<!-- Option 1: Project File (.csproj) -->
<ItemGroup>
    <RuntimeHostConfigurationOption Include="Switch.System.Windows.Appearance.DisableFluentThemeWindowBackdrop" Value="True" />
</ItemGroup>

<!-- Option 2: Runtime Config (.runtimeconfig.json) -->
{
  "runtimeOptions": {
    "tfm": "net9.0",
    "frameworks": [
        // specifications...   
    ],
    "configProperties": {
      "Switch.System.Windows.Appearance.DisableFluentThemeWindowBackdrop": true
    }
  }
}

In WPF on .NET Core, GenAPI is used to create C# reference assemblies by stripping out internal types and members. This prevents dangling references to assemblies not present in the WindowsDesktop reference pack.

GenAPI is run on-demand when a change to a runtime assembly creates new public surface area, which would otherwise trigger an [ApiCompat] error. To run GenAPI, set the GenerateReferenceAssemblySource MSBuild property to true during a build. This generates a {AssemblyName}.cs file in the ref directory of the assembly's source tree.

/p:GenerateReferenceAssemblySource=true