Skip to content

Commit a4934fb

Browse files
learn-build-service-prod[bot]learn-build-service-prod[bot]
authored
Merge pull request #6612 from MicrosoftDocs/main639112875650256945sync_temp
For protected branch, push strategy should use PR and merge to target branch method to work around git push error
2 parents c7b1c63 + 6d1799e commit a4934fb

5 files changed

Lines changed: 243 additions & 11 deletions

File tree

‎uwp/dotnet-native/getting-started-with-net-native.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ ms.assetid: fc9e04e8-2d05-4870-8cd6-5bd276814afc
77
---
88
# Getting Started with .NET Native
99

10+
> [!IMPORTANT]
11+
> **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 the latest .NET with Native AOT](modernize-uwp-apps-with-dotnet.md) instead of .NET Native. UWP support for modern .NET is now generally available and is the **default project type for C# UWP apps in Visual Studio 2026**. This provides access to the latest .NET and C# features, improved tooling and debugging support, and faster build times. .NET Native will continue to receive security and reliability fixes but will not receive new feature updates.
12+
1013
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:
1114

1215
1. [Develop a Universal Windows Platform (UWP) app](#Step1), and test the debug builds of your app to ensure that it works properly.

‎uwp/dotnet-native/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ ms.assetid: 47cd5648-9469-4b1d-804c-43cc04384045
1111
---
1212
# Compile apps with .NET Native
1313

14+
> [!IMPORTANT]
15+
> **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 the latest .NET with Native AOT](modernize-uwp-apps-with-dotnet.md) instead of .NET Native. UWP support for modern .NET is now generally available and is the **default project type for C# UWP apps in Visual Studio 2026**. This provides access to the latest .NET and C# features, improved tooling and debugging support, and faster build times. .NET Native will continue to receive security and reliability fixes but will not receive new feature updates.
16+
1417
.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.
1518

1619
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:

‎uwp/dotnet-native/modernize-uwp-apps-with-dotnet.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
description: Learn how to modernize your UWP app with the latest .NET and Native AOT for improved performance, modern features, and better tooling.
3+
title: Modernize your UWP app with .NET and Native AOT
4+
ms.date: 01/26/2026
5+
ms.topic: how-to
6+
keywords: windows, uwp, .net, native aot, dotnet, modernization
7+
ms.localizationpriority: high
8+
---
9+
10+
# Modernize your UWP app with .NET and Native AOT
11+
12+
UWP support for modern .NET is now generally available and is the **default project type for C# UWP apps in Visual Studio 2026**. Visual Studio 2026 includes built-in project templates to create new UWP applications, class libraries, and Windows Runtime components using the [latest .NET](https://dotnet.microsoft.com).
13+
14+
> [!NOTE]
15+
> This article refers to [.NET Native](index.md), the legacy precompilation technology for UWP apps. .NET Native will continue to receive security and reliability fixes but will not receive new feature updates. If you're currently using .NET Native, this guide will help you understand the benefits of migrating to modern .NET with Native AOT.
16+
17+
## Why modernize to modern .NET?
18+
19+
Upgrading your UWP app from [.NET Native](index.md) to the [latest .NET](https://dotnet.microsoft.com) with Native AOT provides several key benefits:
20+
21+
### Access to Modern .NET Features
22+
- **Latest .NET and C# features**: Use the [latest .NET](https://dotnet.microsoft.com) with all modern language features and APIs
23+
- **Active development**: [.NET Native](index.md) will continue to receive security and reliability fixes but will not receive new feature updates. Modern .NET is actively developed with regular feature releases
24+
- **Better library compatibility**: Reference newer versions of NuGet packages that only support .NET 6 and above
25+
26+
### Improved Developer Experience
27+
- **Faster build times**: Significantly faster compilation compared to [.NET Native](index.md)
28+
- **Better debugging support**: Enhanced debugging tools and diagnostic capabilities for AOT and trimming issues
29+
- **SDK-style project files**: Modern, clean .csproj files without verbose legacy-style configurations
30+
- **XAML Hot Reload**: Full support for XAML and C# Hot Reload during development
31+
- **Better tooling**: IntelliSense, Live Preview, and XAML Diagnostics work seamlessly
32+
33+
### Performance Benefits
34+
- **Native AOT compilation**: Similar or better startup performance compared to [.NET Native](index.md)
35+
- **Optimized runtime**: Performance improvements through inter-procedural optimizations
36+
- **Static validation**: Catch AOT compatibility issues at build time with analyzers and annotations
37+
38+
### Incremental Migration Path to WinUI 3
39+
Rather than migrating both the .NET runtime and UI framework simultaneously, you can now take an incremental approach:
40+
1. First, migrate to the latest .NET and validate Native AOT compatibility
41+
2. Then, separately migrate from UWP XAML to WinUI 3 and the Win32 app model
42+
43+
This two-step approach reduces risk and makes the migration more manageable.
44+
45+
## Prerequisites
46+
47+
To develop UWP apps with modern .NET, you need:
48+
49+
- **Visual Studio 2026**
50+
- **Universal Windows Platform tools** workload
51+
- **Windows SDK 10.0.26100.0 or later**
52+
53+
### Installation Steps
54+
55+
1. Open the Visual Studio Installer
56+
2. Under **Workloads** > **Desktop & Mobile**, select the **Windows application development** workload
57+
3. Under **Optional** (in the right pane), select:
58+
- **Universal Windows Platform tools** - Contains all tooling for UWP apps
59+
- **Windows 11 SDK (10.0.26100.0)** - Required to build UWP XAML apps
60+
61+
## Creating a New UWP Project with Modern .NET
62+
63+
Visual Studio 2026 includes several project templates for UWP with the latest .NET. **The default C# UWP project templates now target modern .NET** instead of .NET Native:
64+
65+
- **Blank UWP App**: Standard UWP XAML application with single-project MSIX packaging
66+
- **Blank UWP CoreApplication App**: For advanced scenarios with Composition/DirectX content (no XAML)
67+
- **UWP Windows Runtime Component**: Managed WinRT component using latest .NET and CsWinRT
68+
- **UWP Class Library**: Class library with XAML support
69+
70+
> [!TIP]
71+
> Legacy .NET Native templates (marked as ".NET Native") are still available for compatibility, but the modern .NET templates are recommended for all new development.
72+
73+
### Create a New Project
74+
75+
1. In Visual Studio, select **File** > **New** > **Project**
76+
2. Filter by **C#** and **UWP** in the project type dropdown
77+
3. Select **Blank UWP App** template
78+
4. Enter your project name and select **Create**
79+
5. Choose your target and minimum Windows versions
80+
81+
## Understanding UWP Modern .NET Projects
82+
83+
UWP modern .NET projects use SDK-style .csproj files with key properties:
84+
85+
```xml
86+
<Project Sdk="Microsoft.NET.Sdk">
87+
<PropertyGroup>
88+
<OutputType>WinExe</OutputType>
89+
<TargetFramework>net10.0-windows10.0.26100.0</TargetFramework> <!-- Use the latest supported .NET version -->
90+
<TargetPlatformMinVersion>10.0.19041.0</TargetPlatformMinVersion>
91+
<UseUwp>true</UseUwp>
92+
<EnableMsixTooling>true</EnableMsixTooling>
93+
<PublishAot>true</PublishAot>
94+
<DisableRuntimeMarshalling>true</DisableRuntimeMarshalling>
95+
</PropertyGroup>
96+
</Project>
97+
```
98+
99+
### Key Properties Explained
100+
101+
- **UseUwp**: References WinRT projections for Windows.UI.Xaml types and configures CsWinRT for UWP compatibility
102+
- **UseUwpTools**: Enables UWP-specific tooling including XAML compiler, project capabilities, and MSIX packaging. Note this property is enabled by default when `UseUwp` is enabled.
103+
- **EnableMsixTooling**: Enables single-project MSIX support (no separate packaging project needed)
104+
- **PublishAot**: Enables Native AOT compilation (required for Microsoft Store publication)
105+
- **DisableRuntimeMarshalling**: Optimizes performance for Native AOT scenarios
106+
107+
## Migrating Existing UWP Apps to Modern .NET
108+
109+
To migrate an existing UWP app from [.NET Native](index.md) to modern .NET:
110+
111+
### Step 1: Update Project File
112+
113+
1. Convert your existing .csproj to SDK-style format
114+
2. Add the required properties (`UseUwp`, `EnableMsixTooling`, `PublishAot`)
115+
3. Update NuGet package references to versions compatible with the latest .NET
116+
117+
### Step 2: Address Native AOT Compatibility
118+
119+
Native AOT requires all code to be AOT-compatible. Common issues include:
120+
121+
- **Reflection usage**: Add appropriate attributes or use source generators
122+
- **Dynamic code generation**: Replace with compile-time alternatives
123+
- **Third-party libraries**: Ensure all dependencies support Native AOT
124+
125+
For more information on AOT compatibility:
126+
- [Fixing trim warnings](/dotnet/core/deploying/trimming/fixing-warnings)
127+
- [Known trimming incompatibilities](/dotnet/core/deploying/trimming/incompatibilities)
128+
- [Intrinsic APIs marked RequiresDynamicCode](/dotnet/core/deploying/native-aot/intrinsic-requiresdynamiccode-apis)
129+
130+
Application code projects:
131+
132+
```xml
133+
<PropertyGroup>
134+
<PublishAot>true</PublishAot>
135+
</PropertyGroup>
136+
```
137+
138+
The following can be set in library projects:
139+
140+
```xml
141+
<PropertyGroup>
142+
<IsAotCompatible>true</IsAotCompatible>
143+
</PropertyGroup>
144+
```
145+
146+
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.
147+
148+
> [!TIP]
149+
Use `[GeneratedBindableCustomProperty]` classes that need `{Binding}` in XAML. These classes should be marked as `partial`.
150+
151+
### Step 3: Test Thoroughly
152+
153+
1. Build your app in Release mode with Native AOT enabled
154+
2. Test all functionality - AOT-compiled code behaves identically to Debug builds when properly annotated
155+
3. Resolve any trim or AOT warnings before publishing
156+
157+
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).
158+
159+
## Native AOT vs .NET Native
160+
161+
While both compile your app to native code, Native AOT differs from [.NET Native](index.md) in important ways:
162+
163+
### Static Validation
164+
- **Native AOT**: Uses static analysis with code annotations and analyzers to validate AOT compatibility at build time
165+
- **[.NET Native](index.md)**: Uses heuristics and fallback logic that can lead to runtime crashes difficult to debug
166+
167+
### Performance & Size
168+
- **Startup Performance**: Native AOT provides similar or better startup performance (~5% improvement in benchmarks)
169+
- **Binary Size**: Expect ~4MB increase for smaller apps due to self-contained deployment (no shared framework package)
170+
- **Runtime Performance**: Better performance for backend code through inter-procedural optimizations
171+
172+
### Developer Experience
173+
- **Native AOT**: Problems surface during development with clear error messages and debugging support
174+
- **[.NET Native](index.md)**: Slow build times, differences between Debug/Release, and difficult-to-diagnose runtime issues
175+
176+
### Reflection and Metadata
177+
- **Native AOT**: Uses compile-time attributes like `[DynamicallyAccessedMembers]` and source generators to handle reflection
178+
- **[.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
179+
180+
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).
181+
182+
## Publishing to Microsoft Store
183+
184+
When publishing UWP apps with modern .NET to the Microsoft Store:
185+
186+
1. Build in Release configuration with either `PublishAot` or `SelfContained` enabled
187+
2. Ensure no AOT or trim warnings are present
188+
3. Create MSIX package as usual
189+
4. Upload to Partner Center
190+
191+
> [!NOTE]
192+
> 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.
193+
194+
## Advanced Scenarios
195+
196+
### UWP XAML Islands
197+
198+
With modern .NET, you can host UWP XAML controls inside Win32 apps (WinForms, WPF, WinUI 3). This enables:
199+
200+
- Hosting UWP controls like MapControl in full-trust packaged apps
201+
- Single-project solution combining Win32 app and UWP components
202+
- Single native binary without separate build toolchains
203+
204+
### Using Latest NuGet Packages
205+
206+
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).
207+
208+
## Additional Resources
209+
210+
- [Introduction to Native AOT deployment](/dotnet/core/deploying/native-aot/)
211+
- [Prepare .NET libraries for trimming](/dotnet/core/deploying/trimming/prepare-libraries-for-trimming)
212+
- [Create a "Hello, World!" UWP app](../get-started/create-a-hello-world-app-xaml-universal.md)
213+
- [Windows App SDK and WinUI 3](/windows/apps/windows-app-sdk/) - Recommended for new Windows apps
214+
215+
## See Also
216+
217+
### .NET Native Documentation (Legacy)
218+
- [Compiling Apps with .NET Native](index.md) - Overview of .NET Native technology
219+
- [Getting Started with .NET Native](getting-started-with-net-native.md) - How to use .NET Native
220+
- [.NET Native and Compilation](net-native-and-compilation.md) - Understanding .NET Native compilation
221+
- [Runtime Directives (rd.xml) Configuration File Reference](runtime-directives-rd-xml-configuration-file-reference.md) - .NET Native metadata configuration
222+
223+
### Migration Resources
224+
- [Windows App SDK migration guidance](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/overall-migration-strategy)
225+
- [MSIX packaging](/windows/msix/)

‎uwp/get-started/create-a-hello-world-app-xaml-universal.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
---
22
ms.assetid: 03A74239-D4B6-4E41-B2FA-6C04F225B844
3-
title: Learn to create a Hello World UWP app with XAML and .NET 9
4-
description: Use XAML with C# to create a simple Hello, world app that targets the Universal Windows Platform (UWP) and .NET 9 on Windows.
5-
ms.date: 04/30/2025
3+
title: Learn to create a Hello World UWP app with XAML and C#
4+
description: Use XAML with C# to create a simple Hello, world app that targets the Universal Windows Platform (UWP) on Windows.
5+
ms.date: 01/26/2026
66
ms.topic: how-to
77
keywords: windows 10, uwp, first app, hello world, windows 11, xaml, c#, universal windows platform, uwp app, uwp tutorial
88
ms.localizationpriority: medium
99
# Customer intent: As a Windows developer, I want to learn how to create a "Hello, World!" UWP app using Visual Studio, XAML, and C#.
1010
---
1111

12-
# Create a "Hello, World!" UWP app (XAML) with .NET 9
12+
# Create a "Hello, World!" UWP app (XAML)
1313

14-
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.
14+
This tutorial teaches you how to use XAML and C# 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.
1515

1616
Here you'll learn how to:
1717

18-
- Create a new **UWP** project targeting .NET 9 in **Visual Studio**.
18+
- Create a new **UWP** project in **Visual Studio**.
1919
- Write XAML to change the UI on your start page.
2020
- Run the project on the local desktop in Visual Studio.
2121
- Use a [SpeechSynthesizer](/uwp/api/windows.media.speechsynthesis.speechsynthesizer) to make the app talk when you press a button.
@@ -27,7 +27,7 @@ Here you'll learn how to:
2727
- 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.
2828

2929
> [!NOTE]
30-
> 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.
30+
> 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.
3131
3232
## Step 1: Create a new project in Visual Studio
3333

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

4646
> [!IMPORTANT]
47-
> 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/).
47+
> The **UWP Blank App** template is the default and targets the latest .NET with Native AOT. If you see a **UWP Blank App (.NET Native)** template, that is a legacy template targeting the older .NET Native runtime. Apps using the modern .NET template have access to the latest .NET and C# features, improved performance, and better tooling. For more information about the differences, see [Modernize your UWP app with .NET and Native AOT](../dotnet-native/modernize-uwp-apps-with-dotnet.md).
4848
4949
1. Select **Next**, and enter "HelloWorld" as the **Project name**. Select **Create**.
5050

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

112112
> [!NOTE]
113-
> 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.
113+
> You won't see a design view when working with the **UWP Blank App** template that uses modern .NET. 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 modern .NET template.
114114
115115
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:
116116

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

215215
## Summary
216216

217-
Congratulations, you've created your first UWP app for Windows with .NET 9!
217+
Congratulations, you've created your first UWP app for Windows with modern .NET!
218218

219219
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)?
220220

0 commit comments

Comments
 (0)