Edit

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

  • Article

ASP.NET Core 8.0 introduces support for .NET native ahead-of-time (AOT).

Note

  • The Native AOT feature is currently in preview.
  • In .NET 8, not all ASP.NET Core features are compatible with Native AOT.
  • Tabs are provided for the .NET Core CLI and Visual Studio instructions:
    • Visual Studio is a prerequisite even if the CLI tab is selected.
    • The CLI must be used to publish even if the Visual Studio tab is selected.

Prerequisites

Note

Visual Studio 2022 Preview 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.

Create a web app with Native AOT

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

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.

Publish the Native AOT app

Verify the app can be published using Native AOT:

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

Libraries and Native AOT

Many of the popular libraries used in ASP.NET Core projects currently have some compatibility issues when used in a project targeting Native AOT, such as:

  • Use of reflection to inspect and discover types.
  • Conditionally loading libraries at runtime.
  • Generating code on the fly to implement functionality.

Libraries using these dynamic features need to be updated in order to work with Native AOT. They can be updated using tools like Roslyn source generators.

Library authors hoping to support Native AOT are encouraged to:

See also