Skip to content

Update modern .NET C# UWP app documentation #5803

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
tommcdon wants to merge 2 commits into
base: docs
Choose a base branch
from
+234 −11
Draft

Update modern .NET C# UWP app documentation #5803

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
28cbe8a
Update UWP documentation to reflect .NET 10 and Native AOT recommenda…
tommcdon Jan 26, 2026
f2f736f
Add links for .NET Native and update recommendations
tommcdon Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions uwp/dotnet-native/getting-started-with-net-native.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ ms.assetid: fc9e04e8-2d05-4870-8cd6-5bd276814afc
---
# Getting Started with .NET Native

> [!IMPORTANT]
> **Modernize your UWP app with .NET and Native AOT**: If you are developing a new UWP app or want to modernize an existing UWP app, we recommend using [UWP support for .NET 10 with Native AOT](modernize-uwp-apps-with-dotnet.md) instead of .NET Native. UWP support for modern .NET is now generally available in Visual Studio 2026, with built-in project templates. This provides access to the latest .NET and C# features, improved tooling and debugging support, and faster build times. .NET Native (documented below) is limited to the .NET Core 2.0 feature level and only receives security updates.

Whether you're writing a new UWP app or migrating an existing Windows 8.x app (previously also called a Microsoft Store app), you can follow the same set of procedures. To create a .NET Native app, follow these steps:

1. [Develop a Universal Windows Platform (UWP) app](#Step1), and test the debug builds of your app to ensure that it works properly.
Expand Down
3 changes: 3 additions & 0 deletions uwp/dotnet-native/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,9 @@ ms.assetid: 47cd5648-9469-4b1d-804c-43cc04384045
---
# Compile apps with .NET Native

> [!IMPORTANT]
> **Modernize your UWP app with .NET and Native AOT**: If you are developing a new UWP app or want to modernize an existing UWP app, we recommend using [UWP support for .NET 10 with Native AOT](modernize-uwp-apps-with-dotnet.md) instead of .NET Native. UWP support for modern .NET is now generally available in Visual Studio 2026, with built-in project templates. This provides access to the latest .NET and C# features, improved tooling and debugging support, and faster build times. .NET Native (documented below) is limited to the .NET Core 2.0 feature level and only receives security updates.

.NET Native is a precompilation technology for building and deploying UWP apps. .NET Native is included with Visual Studio 2015 and later versions. It automatically compiles the release version of UWP apps that are written in managed code (C# or Visual Basic) to native code.

Typically, .NET apps are compiled to intermediate language (IL). At run time, the just-in-time (JIT) compiler translates the IL to native code. In contrast, .NET Native compiles UWP apps directly to native code. For developers, this means:
Expand Down
216 changes: 216 additions & 0 deletions uwp/dotnet-native/modernize-uwp-apps-with-dotnet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,216 @@
---
description: Learn how to modernize your UWP app with .NET 10 and Native AOT for improved performance, modern features, and better tooling.
title: Modernize your UWP app with .NET and Native AOT
ms.date: 01/26/2026
ms.topic: how-to
keywords: windows, uwp, .net 10, native aot, dotnet, modernization
ms.localizationpriority: high
---

# Modernize your UWP app with .NET and Native AOT

UWP support for modern .NET is now generally available, providing a path for existing UWP developers to modernize their apps with the latest .NET and Native AOT compilation. Visual Studio 2026 includes built-in project templates to create new UWP applications, class libraries, and Windows Runtime components using .NET 10.

> [!NOTE]
> This article refers to [.NET Native](index.md), the legacy precompilation technology for UWP apps that is limited to .NET Core 2.0 feature level and only receives security updates. If you're currently using .NET Native, this guide will help you understand the benefits of migrating to modern .NET with Native AOT.

## Why modernize to modern .NET?

Upgrading your UWP app from [.NET Native](index.md) to .NET 10 with Native AOT provides several key benefits:

### Access to Modern .NET Features
- **Latest .NET and C# features**: Use .NET 10 with all modern language features and APIs
- **Active development**: Unlike [.NET Native](index.md) which only receives security updates and is limited to .NET Core 2.0 feature level, .NET 10 is actively developed
- **Better library compatibility**: Reference newer versions of NuGet packages that only support .NET 6 and above

### Improved Developer Experience
- **Faster build times**: Significantly faster compilation compared to [.NET Native](index.md)
- **Better debugging support**: Enhanced debugging tools and diagnostic capabilities for AOT and trimming issues
- **SDK-style project files**: Modern, clean .csproj files without verbose legacy-style configurations
- **XAML Hot Reload**: Full support for XAML and C# Hot Reload during development
- **Better tooling**: IntelliSense, Live Preview, and XAML Diagnostics work seamlessly

### Performance Benefits
- **Native AOT compilation**: Similar or better startup performance compared to [.NET Native](index.md)
- **Optimized runtime**: Performance improvements through inter-procedural optimizations
- **Static validation**: Catch AOT compatibility issues at build time with analyzers and annotations

### Incremental Migration Path to WinUI 3
Rather than migrating both the .NET runtime and UI framework simultaneously, you can now take an incremental approach:
1. First, migrate to .NET 10 and validate Native AOT compatibility
2. Then, separately migrate from UWP XAML to WinUI 3 and the Win32 app model

This two-step approach reduces risk and makes the migration more manageable.

## Prerequisites

To develop UWP apps with .NET 10, you need:

- **Visual Studio 2026**
- **Universal Windows Platform tools** workload
- **Windows SDK 10.0.26100.0 or later**

### Installation Steps

1. Open the Visual Studio Installer
2. Under **Workloads** > **Desktop & Mobile**, select the **Windows application development** workload
3. Under **Optional** (in the right pane), select:
- **Universal Windows Platform tools** - Contains all tooling for UWP apps
- **Windows 11 SDK (10.0.26100.0)** - Required to build UWP XAML apps

## Creating a New UWP .NET 10 Project

Visual Studio includes several project templates for UWP with .NET 10:

- **Blank UWP App**: Standard UWP XAML application with single-project MSIX packaging
- **Blank UWP CoreApplication App**: For advanced scenarios with Composition/DirectX content (no XAML)
- **UWP Windows Runtime Component**: Managed WinRT component using latest .NET and CsWinRT
- **UWP Class Library**: Class library with XAML support

> [!TIP]
> Legacy .NET Native templates (marked as ".NET Native") are still available for compatibility, but the modern .NET 10 templates are recommended for all new development.

### Create a New Project

1. In Visual Studio, select **File** > **New** > **Project**
2. Filter by **C#** and **UWP** in the project type dropdown
3. Select **Blank UWP App** template
4. Enter your project name and select **Create**
5. Choose your target and minimum Windows versions

## Understanding UWP .NET 10 Projects

UWP .NET 10 projects use modern SDK-style .csproj files with key properties:

```xml
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net10.0-windows10.0.19041.0</TargetFramework>
<TargetPlatformMinVersion>10.0.19041.0</TargetPlatformMinVersion>
<UseUwp>true</UseUwp>
<UseUwpTools>true</UseUwpTools>
<EnableMsixTooling>true</EnableMsixTooling>
<PublishAot>true</PublishAot>
<DisableRuntimeMarshalling>true</DisableRuntimeMarshalling>
</PropertyGroup>
</Project>
```

### Key Properties Explained

- **UseUwp**: References WinRT projections for Windows.UI.Xaml types and configures CsWinRT for UWP compatibility
- **UseUwpTools**: Enables UWP-specific tooling including XAML compiler, project capabilities, and MSIX packaging
- **EnableMsixTooling**: Enables single-project MSIX support (no separate packaging project needed)
- **PublishAot**: Enables Native AOT compilation (required for Microsoft Store publication)
- **DisableRuntimeMarshalling**: Optimizes performance for Native AOT scenarios

> [!IMPORTANT]
> Native AOT is the only supported way for publishing UWP apps targeting modern .NET to the Microsoft Store. This ensures fast startup times and meets the Store's native code requirement for UWP apps.

## Migrating Existing UWP Apps to .NET 10

To migrate an existing UWP app from [.NET Native](index.md) to .NET 10:

### Step 1: Update Project File

1. Convert your existing .csproj to SDK-style format
2. Add the required properties (`UseUwp`, `UseUwpTools`, `EnableMsixTooling`, `PublishAot`)
3. Update NuGet package references to versions compatible with .NET 10

> [!TIP]
> If your existing app uses a [runtime directives (rd.xml) file](runtime-directives-rd-xml-configuration-file-reference.md) for .NET Native, you'll need to address reflection and trimming requirements differently with Native AOT using attributes and analyzers instead.

### Step 2: Address Native AOT Compatibility

Native AOT requires all code to be AOT-compatible. Common issues include:

- **Reflection usage**: Add appropriate attributes or use source generators
- **Dynamic code generation**: Replace with compile-time alternatives
- **Third-party libraries**: Ensure all dependencies support Native AOT

Enable AOT analyzers to catch issues at build time:

```xml
<PropertyGroup>
<IsAotCompatible>true</IsAotCompatible>
<EnableTrimAnalyzer>true</EnableTrimAnalyzer>
<EnableSingleFileAnalyzer>true</EnableSingleFileAnalyzer>
</PropertyGroup>
```

### Step 3: Test Thoroughly

1. Build your app in Release mode with Native AOT enabled
2. Test all functionality - AOT-compiled code behaves identically to Debug builds when properly annotated
3. Resolve any trim or AOT warnings before publishing

For more information on Native AOT compatibility, see [Introduction to AOT warnings](/dotnet/core/deploying/native-aot/fixing-warnings) and [Prepare .NET libraries for trimming](/dotnet/core/deploying/trimming/prepare-libraries-for-trimming).

## Native AOT vs .NET Native

While both compile your app to native code, Native AOT differs from [.NET Native](index.md) in important ways:

### Static Validation
- **Native AOT**: Uses static analysis with code annotations and analyzers to validate AOT compatibility at build time
- **[.NET Native](index.md)**: Uses heuristics and fallback logic that can lead to runtime crashes difficult to debug

### Performance & Size
- **Startup Performance**: Native AOT provides similar or better startup performance (~5% improvement in benchmarks)
- **Binary Size**: Expect ~4MB increase for smaller apps due to self-contained deployment (no shared framework package)
- **Runtime Performance**: Better performance for backend code through inter-procedural optimizations

### Developer Experience
- **Native AOT**: Problems surface during development with clear error messages and debugging support
- **[.NET Native](index.md)**: Slow build times, differences between Debug/Release, and difficult-to-diagnose runtime issues

### Reflection and Metadata
- **Native AOT**: Uses compile-time attributes like `[DynamicallyAccessedMembers]` and source generators to handle reflection
- **[.NET Native](index.md)**: Uses [runtime directives (rd.xml) files](runtime-directives-rd-xml-configuration-file-reference.md) to specify metadata requirements at build time

For more information on .NET Native limitations, see [Getting Started with .NET Native](getting-started-with-net-native.md) and [.NET Native and Compilation](net-native-and-compilation.md).

## Publishing to Microsoft Store

When publishing UWP apps with modern .NET to the Microsoft Store:

1. Build in Release configuration with `PublishAot` enabled
2. Ensure no AOT or trim warnings are present
3. Create MSIX package as usual
4. Upload to Partner Center

> [!NOTE]
> You can ignore Windows App Certification Kit (WACK) failures related to "unsupported Win32 APIs." Partner Center no longer performs strict Win32 API validation for UWP apps. AppContainer security handles runtime permissions instead.

## Advanced Scenarios

### UWP XAML Islands

With modern .NET, you can host UWP XAML controls inside Win32 apps (WinForms, WPF, WinUI 3) using a single .NET 10 project. This enables:

- Hosting UWP controls like MapControl in full-trust packaged apps
- Single-project solution combining Win32 app and UWP components
- Single native binary without separate build toolchains

### Using Latest NuGet Packages

Modern .NET support enables you to reference modern NuGet packages that require .NET 6+, removing the limitations of [.NET Native's .NET Standard 2.0 constraint](net-native-and-compilation.md).

## Additional Resources

- [Introduction to Native AOT deployment](/dotnet/core/deploying/native-aot/)
- [Prepare .NET libraries for trimming](/dotnet/core/deploying/trimming/prepare-libraries-for-trimming)
- [Create a "Hello, World!" UWP app with .NET 10](../get-started/create-a-hello-world-app-xaml-universal.md)
- [Windows App SDK and WinUI 3](/windows/apps/windows-app-sdk/) - Recommended for new Windows apps

## See Also

### .NET Native Documentation (Legacy)
- [Compiling Apps with .NET Native](index.md) - Overview of .NET Native technology
- [Getting Started with .NET Native](getting-started-with-net-native.md) - How to use .NET Native
- [.NET Native and Compilation](net-native-and-compilation.md) - Understanding .NET Native compilation
- [Runtime Directives (rd.xml) Configuration File Reference](runtime-directives-rd-xml-configuration-file-reference.md) - .NET Native metadata configuration

### Migration Resources
- [Windows App SDK migration guidance](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/overall-migration-strategy)
- [MSIX packaging](/windows/msix/)
20 changes: 10 additions & 10 deletions uwp/get-started/create-a-hello-world-app-xaml-universal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
ms.assetid: 03A74239-D4B6-4E41-B2FA-6C04F225B844
title: Learn to create a Hello World UWP app with XAML and .NET 9
description: Use XAML with C# to create a simple Hello, world app that targets the Universal Windows Platform (UWP) and .NET 9 on Windows.
ms.date: 04/30/2025
title: Learn to create a Hello World UWP app with XAML and .NET 10
description: Use XAML with C# to create a simple Hello, world app that targets the Universal Windows Platform (UWP) and .NET 10 on Windows.
ms.date: 01/26/2026
ms.topic: how-to
keywords: windows 10, uwp, first app, hello world, windows 11, xaml, c#, universal windows platform, uwp app, uwp tutorial
ms.localizationpriority: medium
# Customer intent: As a Windows developer, I want to learn how to create a "Hello, World!" UWP app using Visual Studio, XAML, and C#.
---

# Create a "Hello, World!" UWP app (XAML) with .NET 9
# Create a "Hello, World!" UWP app (XAML) with .NET 10

This tutorial teaches you how to use XAML, C#, and .NET 9 with [Native AOT](/dotnet/core/deploying/native-aot/) (Ahead-of-Time) to create a simple "Hello, World!" app for the Universal Windows Platform (UWP) on Windows. With a single project in Microsoft Visual Studio, you can build an app that runs on all supported versions of Windows 10 and Windows 11.
This tutorial teaches you how to use XAML, C#, and .NET 10 with [Native AOT](/dotnet/core/deploying/native-aot/) (Ahead-of-Time) to create a simple "Hello, World!" app for the Universal Windows Platform (UWP) on Windows. With a single project in Microsoft Visual Studio, you can build an app that runs on all supported versions of Windows 10 and Windows 11.

Here you'll learn how to:

- Create a new **UWP** project targeting .NET 9 in **Visual Studio**.
- Create a new **UWP** project targeting .NET 10 in **Visual Studio**.
- Write XAML to change the UI on your start page.
- Run the project on the local desktop in Visual Studio.
- Use a [SpeechSynthesizer](/uwp/api/windows.media.speechsynthesis.speechsynthesizer) to make the app talk when you press a button.
Expand All @@ -27,7 +27,7 @@ Here you'll learn how to:
- We also assume you're using the default window layout in Visual Studio. If you change the default layout, you can reset it in the **Window** menu by using the **Reset Window Layout** command.

> [!NOTE]
> This tutorial is using Visual Studio 2022. If you are using a different version of Visual Studio, it may look a little different for you.
> This tutorial is using Visual Studio 2026. If you are using a different version of Visual Studio, it may look a little different for you.

## Step 1: Create a new project in Visual Studio

Expand All @@ -44,7 +44,7 @@ Here you'll learn how to:
1. Choose the **UWP Blank App** template.

> [!IMPORTANT]
> Make sure to select the **UWP Blank App** template. If you select the **UWP Blank App (.NET Native)** template, it will target the .NET Native runtime, not .NET 9. Apps targeting .NET Native do not have access to the latest .NET and C# features or security and performance improvements. For more information about the differences between the two project types, see [Modernize your UWP app with preview UWP support for .NET 9 and Native AOT](https://devblogs.microsoft.com/ifdef-windows/preview-uwp-support-for-dotnet-9-native-aot/).
> Make sure to select the **UWP Blank App** template. If you select the **UWP Blank App (.NET Native)** template, it will target the .NET Native runtime, not .NET 10. Apps targeting .NET Native do not have access to the latest .NET and C# features or security and performance improvements. For more information about the differences between the two project types, see [Modernize your UWP app with .NET and Native AOT](../dotnet-native/modernize-uwp-apps-with-dotnet.md).

1. Select **Next**, and enter "HelloWorld" as the **Project name**. Select **Create**.

Expand Down Expand Up @@ -110,7 +110,7 @@ Let's add a button to our page. In this tutorial, you work with just a few of th
![A screenshot of Visual Studio showing the Main Page in the X A M L editor](images/cs-xaml-hw-app4.png)

> [!NOTE]
> You won't see a design view when working with the **UWP Blank App** template that uses .NET 9. If you want to work with a UWP project with a XAML design view, you can use the **UWP Blank App (.NET Native)** template instead. As previously noted, the **UWP Blank App (.NET Native)** template is a little different from the **UWP Blank App** template, but it has the same basic structure. The main difference is that the **UWP Blank App (.NET Native)** template uses .NET Native to compile your app. See [Modernize your UWP app with preview UWP support for .NET 9 and Native AOT](https://devblogs.microsoft.com/ifdef-windows/preview-uwp-support-for-dotnet-9-native-aot/) for information about the advantages of using the new .NET 9 template.
> You won't see a design view when working with the **UWP Blank App** template that uses .NET 10. If you want to work with a UWP project with a XAML design view, you can use the **UWP Blank App (.NET Native)** template instead. As previously noted, the **UWP Blank App (.NET Native)** template is a little different from the **UWP Blank App** template, but it has the same basic structure. The main difference is that the **UWP Blank App (.NET Native)** template uses .NET Native to compile your app. See [Modernize your UWP app with .NET and Native AOT](../dotnet-native/modernize-uwp-apps-with-dotnet.md) for information about the advantages of using the new .NET 10 template.

1. Add the following XAML code to the `<Grid>` element in MainPage.xaml. You can type it in, or copy and paste it from here:

Expand Down Expand Up @@ -214,7 +214,7 @@ When you run the app and click on the button, your computer (or phone) will lite

## Summary

Congratulations, you've created your first UWP app for Windows with .NET 9!
Congratulations, you've created your first UWP app for Windows with .NET 10!

To learn how to use XAML for laying out the controls your app will use, try the [grid tutorial](/windows/apps/design/layout/grid-tutorial), or jump straight to [next steps](create-uwp-apps.md)?

Expand Down
Loading