Skip to main content

Upgrading to XPF 2

This guide covers how to upgrade your XPF app to XPF version 2. It is intended for existing apps that are currently using XPF version 1.

Summary of changes in XPF 2​

How to upgrade​

To upgrade your app from XPF version 1 to version 2, you must do the following:

  1. Update your project to .NET version 10.
  2. Update the XPF SDK version.
  3. Update your project to Avalonia version 12, if currently using assemblies from an earlier version.
  4. Change your license key.
  5. (Beta) Add any missing packages.

Step 1: Update your project to .NET version 10​

If your project uses a .NET version lower than 10, you must update it to at least net10.0-windows. You can use the GitHub Copilot upgrade agent to assist you.

Confirm that your project builds and runs correctly on .NET 10 (or later) with WPF before proceeding.

danger

XPF 2.x is not compatible with any project targeting a version of .NET below 10.

Step 2: Update the XPF SDK version​

In the .csproj file of the executable WPF project, update the XPF SDK to a 2.x version number.

<Project Sdk="Xpf.Sdk/2.0.0-beta1">
note

You can check the latest SDK version at https://xpf-nuget-feed.avaloniaui.net/packages/xpf.sdk. See Versioning for more information.

Step 3: Update your project to Avalonia version 12​

If your project directly references any Avalonia assemblies from version 11 (or earlier), they should be updated to version 12 to ensure compatibility with XPF version 2.

See Breaking changes in Avalonia 12 for guidance on major changes in this Avalonia version.

Step 4: Change your license key​

XPF version 2 requires a different license key from version 1. Your new license key is available from the Avalonia portal. Look for XPF v2 License Key.

Copy your license key into your executable's .csproj file using the <AvaloniaUILicenseKey> tag. Remove the old license key along with its RuntimeHostConfigurationOption tag, which is no longer recognized in XPF version 2.

<ItemGroup>
  <!-- Add your new license key -->
  <AvaloniaUILicenseKey Include="YOUR_LICENSE_KEY" />

  <!-- Remove this line -->
  <RuntimeHostConfigurationOption Include="AvaloniaUI.Xpf.LicenseKey" Value="OLD_LICENSE_KEY" />
</ItemGroup>
info

This is the same licensing process as used by Avalonia Pro.

Step 5: (Beta) Add any missing packages​

Some packages are not included in the beta release of XPF version 2. If you find that any packages are missing, you must explicitly reference them with a <PackageReference> in your .csproj file, for example:

<ItemGroup>
  <PackageReference Include="System.Security.Permissions" Version="10.0.10" />
</ItemGroup>

Step 6: Run the project​

Confirm the upgraded project runs using your preferred IDE or dotnet run.

Opt into Wayland​

If you wish to use Wayland with your XPF app on Linux, opt in by adding the following to your .csproj file.

<PropertyGroup>
  <XpfEnableWayland>true</XpfEnableWayland>
</PropertyGroup>

Avalonia's Wayland backend is at an early stage of development and does not yet provide the same features as other backends. For more information, see Wayland.

See also​

On this page