Skip to content

native-aot-tutorial.md

Latest commit

 

History

History
174 lines (124 loc) · 6.54 KB

native-aot-tutorial.md

File metadata and controls

174 lines (124 loc) · 6.54 KB
title Tutorial: Publish an ASP.NET Core app using Native AOT
author mitchdenny
description Learn about how to publish an ASP.NET Core app using Native AOT.
monikerRange >= aspnetcore-8.0
ms.topic tutorial
content_well_notification AI-contribution
ms.author midenn
ms.custom mvc
ms.date 05/13/2025
uid fundamentals/native-aot-tutorial
ai-usage ai-assisted

Tutorial: Publish an ASP.NET Core app using Native AOT

.NET native ahead-of-time (AOT) is available in ASP.NET Core.

Note

Minimal APIs are not compatible with native AOT.

See Native AOT deployment for more information, including:

Prerequisites

.NET CLI

Note

Visual Studio 2022 is required because Native AOT requires link.exe and the Visual C++ static runtime libraries. There are no plans to support Native AOT without Visual Studio.

Visual Studio

.NET SDK

  • Visual Studio 2022 with the following workloads installed:

    • ASP.NET and web development
    • Desktop development with C++

    Visual Studio workload selection dialog showing "ASP.NET and web development" and "Desktop development with C++" selected.

Create a web app with Native AOT

Create an ASP.NET Core API app that is configured to work with Native AOT:

.NET CLI

Run the following commands:

dotnet new webapiaot -o MyFirstAotWebApi && cd MyFirstAotWebApi

Output similar to the following example is displayed:

The template "ASP.NET Core Web API (Native AOT)" was created successfully.

Processing post-creation actions...
Restoring C:\Code\Demos\MyFirstAotWebApi\MyFirstAotWebApi.csproj:
  Determining projects to restore...
  Restored C:\Code\Demos\MyFirstAotWebApi\MyFirstAotWebApi.csproj (in 302 ms).
Restore succeeded.

Visual Studio

  1. Create a new ASP.NET Core Web API (Native AOT) project.
  2. Name the project MyFirstAotWebApi.
  3. Select Create.

Publish the Native AOT app

Verify the app can be published using Native AOT:

.NET CLI

dotnet publish

Visual Studio

Visual studio doesn't support publishing an AOT app. Use the CLI command:

dotnet publish

The dotnet publish command:

  • Compiles the source files.
  • Generates source code files that are compiled.
  • Passes generated assemblies to a native IL compiler. The IL compiler produces the native executable. The native executable contains the native machine code.

Output similar to the following example is displayed:

MSBuild version 17.<version> for .NET
  Determining projects to restore...
  Restored C:\Code\Demos\MyFirstAotWebApi\MyFirstAotWebApi.csproj (in 241 ms).
C:\Code\dotnet\aspnetcore\.dotnet\sdk\8.0.<version>\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.RuntimeIde
ntifierInference.targets(287,5): message NETSDK1057: You are using a preview version of .NET. See: https://aka.ms/dotne
t-support-policy [C:\Code\Demos\MyFirstAotWebApi\MyFirstAotWebApi.csproj]
  MyFirstAotWebApi -> C:\Code\Demos\MyFirstAotWebApi\bin\Release\net8.0\win-x64\MyFirstAotWebApi.dll
  Generating native code
  MyFirstAotWebApi -> C:\Code\Demos\MyFirstAotWebApi\bin\Release\net8.0\win-x64\publish\

The output may differ from the preceding example depending on the version of .NET 8 used, directory used, and other factors.

Review the contents of the output directory:

dir bin\Release\net8.0\win-x64\publish

Output similar to the following example is displayed:

    Directory: C:\Code\Demos\MyFirstAotWebApi\bin\Release\net8.0\win-x64\publish

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---          30/03/2023  1:41 PM        9480704 MyFirstAotWebApi.exe
-a---          30/03/2023  1:41 PM       43044864 MyFirstAotWebApi.pdb

The executable is self-contained and doesn't require a .NET runtime to run. When launched, it behaves the same as the app run in the development environment. Run the AOT app:

.\bin\Release\net8.0\win-x64\publish\MyFirstAotWebApi.exe

Output similar to the following example is displayed:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: C:\Code\Demos\MyFirstAotWebApi

[!INCLUDE]

See also