diff --git a/uwp/dotnet-native/getting-started-with-net-native.md b/uwp/dotnet-native/getting-started-with-net-native.md index 39ea166cfd..27828389c5 100644 --- a/uwp/dotnet-native/getting-started-with-net-native.md +++ b/uwp/dotnet-native/getting-started-with-net-native.md @@ -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. diff --git a/uwp/dotnet-native/index.md b/uwp/dotnet-native/index.md index ebb27ae055..03c6daadff 100644 --- a/uwp/dotnet-native/index.md +++ b/uwp/dotnet-native/index.md @@ -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: diff --git a/uwp/dotnet-native/modernize-uwp-apps-with-dotnet.md b/uwp/dotnet-native/modernize-uwp-apps-with-dotnet.md new file mode 100644 index 0000000000..8f46683149 --- /dev/null +++ b/uwp/dotnet-native/modernize-uwp-apps-with-dotnet.md @@ -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 + + + WinExe + net10.0-windows10.0.19041.0 + 10.0.19041.0 + true + true + true + true + true + + +``` + +### 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 + + true + true + true + +``` + +### 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/) diff --git a/uwp/get-started/create-a-hello-world-app-xaml-universal.md b/uwp/get-started/create-a-hello-world-app-xaml-universal.md index 03a1d75dc4..8b67588744 100644 --- a/uwp/get-started/create-a-hello-world-app-xaml-universal.md +++ b/uwp/get-started/create-a-hello-world-app-xaml-universal.md @@ -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. @@ -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 @@ -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**. @@ -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 `` element in MainPage.xaml. You can type it in, or copy and paste it from here: @@ -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)? diff --git a/uwp/get-started/universal-application-platform-guide.md b/uwp/get-started/universal-application-platform-guide.md index 72d78382cf..151d558d9c 100644 --- a/uwp/get-started/universal-application-platform-guide.md +++ b/uwp/get-started/universal-application-platform-guide.md @@ -148,7 +148,8 @@ For more introductory material, see [An Introduction to Building Windows Apps fo - For the full list of Win32 APIs available to UWP apps, see [API Sets for UWP apps](/previous-versions/mt186421(v=vs.85)) and [Dlls for UWP apps](/previous-versions/mt186422(v=vs.85)). - See [Universal Windows apps in .NET](https://devblogs.microsoft.com/dotnet/universal-windows-apps-in-net/) for an overview of writing .NET UWP apps. - For a list of .NET types that you can use in a UWP app, see [.NET for UWP apps](/dotnet/api/index?view=dotnet-uwp-10.0&preserve-view=true) -- [Compiling apps with .NET Native](/dotnet/framework/net-native/) +- [Modernize your UWP app with .NET and Native AOT](../dotnet-native/modernize-uwp-apps-with-dotnet.md) - Recommended for new and existing UWP apps to access the latest .NET features +- [Compiling apps with .NET Native](/dotnet/framework/net-native/) - Legacy toolchain (security updates only) - Learn how to add modern experiences for Windows users to your existing desktop app, and distribute it in the Microsoft Store with the [Desktop Bridge](/windows/msix/desktop/source-code-overview). ## How the Universal Windows Platform relates to Windows Runtime APIs