Split AOT doc into two docs, tutorial and conceptual (#29358)
Tom Dykstra
GitHub
parent
b2c1c5a322
commit
1b37d13a39
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
|
|
@ -0,0 +1,160 @@
|
|||
---
|
||||
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
|
||||
ms.author: midenn
|
||||
ms.custom: mvc
|
||||
ms.date: 05/25/2023
|
||||
uid: fundamentals/native-aot-tutorial
|
||||
---
|
||||
# Tutorial: Publish an ASP.NET Core app using native AOT
|
||||
|
||||
ASP.NET Core 8.0 introduces support for [.NET native ahead-of-time (AOT)](/dotnet/core/deploying/native-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](/dotnet/core/tools/) and [Visual Studio](https://visualstudio.microsoft.com/vs/preview/) instructions. However, in this early preview installation of Visual Studio is a prerequisite even if the CLI tab is selected. And the CLI must be used to publish even if the Visual Studio tab is selected.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
# [.NET Core CLI](#tab/netcore-cli)
|
||||
|
||||
* [!INCLUDE[](~/includes/8.0-SDK.md)]
|
||||
|
||||
* [Visual Studio 2022 Preview](https://visualstudio.microsoft.com/vs/preview/) with the **Desktop development with C++** workload installed.
|
||||
|
||||
|
||||
|
||||
# [Visual Studio](#tab/visual-studio)
|
||||
|
||||
* [!INCLUDE[](~/includes/8.0-SDK.md)]
|
||||
|
||||
* [Visual Studio 2022 Preview](https://visualstudio.microsoft.com/vs/preview/) with the following workloads installed:
|
||||
* **ASP.NET and web development**
|
||||
* **Desktop development with C++**
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Create a web app with native AOT
|
||||
|
||||
Create an ASP.NET Core API app that is configured to work with native AOT:
|
||||
|
||||
# [.NET Core CLI](#tab/netcore-cli)
|
||||
|
||||
Run the following commands:
|
||||
|
||||
```dotnetcli
|
||||
dotnet new api --aot -o MyFirstAotWebApi && cd MyFirstAotWebApi
|
||||
```
|
||||
|
||||
Output similar to the following example is displayed:
|
||||
|
||||
```output
|
||||
The template "ASP.NET Core API" 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](#tab/visual-studio)
|
||||
|
||||
1. Create a new ASP.NET Core API project. ***Note:*** The ASP.NET Core API project is different than the ASP.NET Core ***Web*** API project.
|
||||
1. Name the project **MyFirstAotWebApi**.
|
||||
1. In the Additional information dialog, select **Enable native AOT publish**.
|
||||
|
||||
|
||||
|
||||
1. Select **Create**.
|
||||
|
||||
---
|
||||
|
||||
## Publish the native AOT app
|
||||
|
||||
Verify the app can be published using native AOT:
|
||||
|
||||
# [.NET Core CLI](#tab/netcore-cli)
|
||||
|
||||
```dotnetcli
|
||||
dotnet publish
|
||||
```
|
||||
|
||||
# [Visual Studio](#tab/visual-studio)
|
||||
|
||||
Visual studio doesn't currently support publishing an AOT app. Use the CLI command:
|
||||
|
||||
```dotnetcli
|
||||
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:
|
||||
|
||||
```output
|
||||
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:
|
||||
|
||||
```Output
|
||||
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 should behave 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:
|
||||
|
||||
```output
|
||||
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
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
* <xref:fundamentals/native-aot>
|
||||
* [Native AOT deployment](/dotnet/core/deploying/native-aot/)
|
||||
|
|
@ -6,7 +6,7 @@ builder.Logging.AddConsole();
|
|||
|
||||
builder.Services.ConfigureHttpJsonOptions(options =>
|
||||
{
|
||||
options.SerializerOptions.AddContext<AppJsonSerializerContext>();
|
||||
options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
|
||||
});
|
||||
|
||||
var app = builder.Build();
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ description: Learn about ASP.NET Core support for native AOT
|
|||
monikerRange: '>= aspnetcore-8.0'
|
||||
ms.author: midenn
|
||||
ms.custom: mvc
|
||||
ms.date: 5/25/2023
|
||||
ms.date: 05/25/2023
|
||||
uid: fundamentals/native-aot
|
||||
---
|
||||
# ASP.NET Core support for native AOT
|
||||
|
|
@ -15,30 +15,58 @@ ASP.NET Core 8.0 introduces support for [.NET native ahead-of-time (AOT)](/dotne
|
|||
> [!WARNING]
|
||||
> In .NET 8, not all ASP.NET Core features are compatible with native AOT.
|
||||
|
||||
## Prerequisites
|
||||
## Why use native AOT with ASP.NET Core
|
||||
|
||||
# [.NET Core CLI](#tab/netcore-cli)
|
||||
Publishing and deploying a native AOT app provides the following benefits:
|
||||
|
||||
* [!INCLUDE[](~/includes/8.0-SDK.md)]
|
||||
* From the Visual Studio installer, add the Desktop development with C++
|
||||
* **Minimized disk footprint**: When publishing using native AOT, a single executable is produced containing just the code from external dependencies that is needed to support the program. Reduced executable size can lead to:
|
||||
* Smaller container images, for example in containerized deployment scenarios.
|
||||
* Reduced deployment time from smaller images.
|
||||
* **Reduced startup time**: Native AOT applications can show reduced start-up times, which means
|
||||
* The app is ready to service requests quicker.
|
||||
* Improved deployment where container orchestrators need to manage transition from one version of the app to another.
|
||||
* **Reduced memory demand**: Native AOT apps can have reduced memory demands, depending on the work done by the app. Reduced memory consumption can lead to greater deployment density and improved scalability.
|
||||
|
||||
|
||||
The template app was run in our benchmarking lab to compare performance of an AOT published app, a trimmed runtime app, and an untrimmed runtime app. The following chart shows the results of the benchmarking:
|
||||
|
||||
# [Visual Studio](#tab/visual-studio)
|
||||
|
||||
|
||||
* [!INCLUDE[](~/includes/8.0-SDK.md)]
|
||||
* [Visual Studio 2022 Preview](https://visualstudio.microsoft.com/vs/preview/)
|
||||
* Workloads:
|
||||
* ASP.NET and web development
|
||||
* Desktop development with C++
|
||||
The preceding chart shows that native AOT has lower app size, memory usage, and startup time.
|
||||
|
||||
|
||||
## ASP.NET Core and native AOT compatibility
|
||||
|
||||
---
|
||||
Not all features in ASP.NET Core are currently compatible with native AOT. The following table summarizes ASP.NET Core feature compatibility with native AOT:
|
||||
|
||||
| Feature | Fully Supported | Partially Supported | Not Supported |
|
||||
| - | - | - | - |
|
||||
| gRPC | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Minimal APIs | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
|
||||
| MVC | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| Blazor Server | | |<span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| SignalR | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| Authentication | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> (JWT soon) |
|
||||
| CORS | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| HealthChecks | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| HttpLogging | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Localization | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| OutputCaching | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| RateLimiting | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| RequestDecompression | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| ResponseCaching | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| ResponseCompression | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Rewrite | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Session | | |<span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| Spa | | |<span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| StaticFiles | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| WebSockets | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
|
||||
It's important to test an app thoroughly when moving to a native AOT deployment model. The AOT deployed app should be tested to verify functionality hasn't changed from the untrimmed and JIT-compiled app. When building the app, review and correct AOT warnings. An app that issues AOT warnings during publishing is not guaranteed to work correctly. If no AOT warnings are issued at publish time, the published AOT app should work the same as when it's run in development.
|
||||
|
||||
For more information, see [Introduction to AOT warnings](/dotnet/core/deploying/native-aot/fixing-warnings).
|
||||
|
||||
## Native AOT publishing
|
||||
|
||||
AOT compilation happens when the app is published. Native AOT is enabled with the `PublishAot` option:
|
||||
Native AOT is enabled with the `PublishAot` MSBuild property. The following example shows how to enable native AOT in a project file:
|
||||
|
||||
```xml
|
||||
<PropertyGroup>
|
||||
|
|
@ -46,132 +74,48 @@ AOT compilation happens when the app is published. Native AOT is enabled with th
|
|||
</PropertyGroup>
|
||||
```
|
||||
|
||||
A project that uses native AOT publishing uses JIT compilation when running locally. The AOT app has the following differences:
|
||||
This setting enables native AOT compilation during publish and enables dynamic code usage analysis during build and editing. A project that uses native AOT publishing uses JIT compilation when running locally. An AOT app has the following differences from a JIT-compiled app:
|
||||
|
||||
* Features that aren't compatible with native AOT are disabled and throw exceptions at runtime.
|
||||
* Features that aren't compatible with native AOT are disabled and throw exceptions at run time.
|
||||
* A source analyzer is enabled to highlight code that isn't compatible with native AOT. At publish time, the entire app, including NuGet packages, are analyzed for compatibility again.
|
||||
|
||||
Native AOT analysis includes all of the app's code and the libraries the app depends on. Review native AOT warnings and take corrective steps. It's a good idea to test publishing apps frequently to discover issues early in the development lifecycle.
|
||||
Native AOT analysis includes all of the app's code and the libraries the app depends on. Review native AOT warnings and take corrective steps. It's a good idea to publish apps frequently to discover issues early in the development lifecycle.
|
||||
|
||||
## Create a web app with native AOT
|
||||
In .NET 8, native AOT is supported by the following ASP.NET Core app types:
|
||||
|
||||
Native AOT is supported by ASP.NET Core minimal APIs and gRPC. For more information about getting started using native AOT with gRPC apps, see [gRPC and native AOT](xref:grpc/native-aot).
|
||||
* minimal APIs - For more information, see the [API template](#the-api-template) section later in this article.
|
||||
* gRPC - For more information, see [gRPC and native AOT](xref:grpc/native-aot).
|
||||
* Worker services - For more information, see [AOT in Worker Service templates](xref:fundamentals/host/hosted-services?view=aspnetcore-8.0&preserve-view=true#native-aot).
|
||||
|
||||
Create an ASP.NET Core API app that is configured to work with native AOT:
|
||||
## The API template
|
||||
|
||||
# [.NET Core CLI](#tab/netcore-cli)
|
||||
The **ASP.NET Core API** template in Visual Studio 2022 has an **Enable native AOT publish** option. The equivalent template and option in the CLI is the `dotnet new api` command and the `--aot` option. This template is intended to produce a project more directly focused on cloud-native, API-first scenarios. The template differs from the **Web API** project template in the following ways:
|
||||
|
||||
Run the following command:
|
||||
* Uses minimal APIs only, as MVC isn't yet compatible with native AOT.
|
||||
* Uses the <xref:Microsoft.AspNetCore.Builder.WebApplication.CreateSlimBuilder> API to ensure only the essential features are enabled by default, minimizing the app's deployed size.
|
||||
* Is configured to listen on HTTP only, as HTTPS traffic is commonly handled by an ingress service in cloud-native deployments.
|
||||
* Doesn't include a launch profile for running under IIS or IIS Express.
|
||||
* Creates an [`.http` file](xref:test/http-files) configured with sample HTTP requests that can be sent to the app's endpoints.
|
||||
* Includes a sample `Todo` API instead of the weather forecast sample.
|
||||
|
||||
```cli
|
||||
dotnet new api --aot -o MyFirstAotWebApi && cd MyFirstAotWebApi
|
||||
```
|
||||
In addition to these differences, the **ASP.NET Core API** template has the following differences when the **Enable native AOT publish** option is selected:
|
||||
|
||||
Output similar to the following is displayed:
|
||||
* Adds `PublishAot` to the project file, as shown [earlier in this article](#native-aot-publishing).
|
||||
* Enables the [JSON serializer source generators](/dotnet/standard/serialization/system-text-json/source-generation). The source generator is used to generate serialization code at build time, which is required for native AOT compilation.
|
||||
|
||||
```cli
|
||||
The template "ASP.NET Core API" was created successfully.
|
||||
### Changes to support source generation
|
||||
|
||||
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](#tab/visual-studio)
|
||||
|
||||
1. Create a new ASP.NET Core API project. ***Note:*** The ASP.NET Core API project is different than the ASP.NET Core ***Web*** API project.
|
||||
1. Select **Enable native AOT publish**
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Publish the native AOT app
|
||||
|
||||
Verify the app can be published using native AOT:
|
||||
|
||||
# [.NET Core CLI](#tab/netcore-cli)
|
||||
|
||||
```cli
|
||||
dotnet publish
|
||||
```
|
||||
|
||||
# [Visual Studio](#tab/visual-studio)
|
||||
|
||||
Visual studio doesn't currently support publishing an AOT app. Use the CLI command:
|
||||
|
||||
```cli
|
||||
dotnet publish
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Output similar to the following is displayed:
|
||||
|
||||
```cli
|
||||
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\
|
||||
```
|
||||
|
||||
Note: The preceding output my differ depending on the version of .NET 8 used, directory used, etc.
|
||||
|
||||
Review the contents of the output directory:
|
||||
|
||||
```cli
|
||||
dir bin\Release\net8.0\win-x64\publish
|
||||
```
|
||||
|
||||
Output similar to the following is displayed:
|
||||
|
||||
```Output
|
||||
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 should behave the same as the app run in the development environment. Run the AOT app:
|
||||
|
||||
```cli
|
||||
.\bin\Release\net8.0\win-x64\publish\MyFirstAotWebApi.exe
|
||||
```
|
||||
|
||||
Output similar to the following is displayed:
|
||||
|
||||
```Output
|
||||
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
|
||||
```
|
||||
|
||||
The following changes are made to the `Program.cs` when the `-aot` option is used:
|
||||
The following example shows the code added to the `Program.cs` file to support JSON serialization source generation:
|
||||
|
||||
```diff
|
||||
|using MyFirstAotWebApi;
|
||||
+using System.Text.Json.Serialization;
|
||||
using MyFirstAotWebApi;
|
||||
|
||||
var builder = WebApplication.CreateSlimBuilder(args);
|
||||
builder.Logging.AddConsole();
|
||||
|
||||
+builder.Services.ConfigureHttpJsonOptions(options =>
|
||||
+{
|
||||
+ options.SerializerOptions.AddContext<AppJsonSerializerContext>();
|
||||
+ options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonSerializerContext.Default);
|
||||
+});
|
||||
|
||||
var app = builder.Build();
|
||||
|
|
@ -194,7 +138,17 @@ app.Run();
|
|||
+}
|
||||
```
|
||||
|
||||
The AOT version of `launchSettings.json` file is simplified and has the `iisSettings` and `IIS Exoress` profile removed:
|
||||
Without this added code, `System.Text.Json` uses reflection to serialize and deserialize JSON. Reflection isn't supported in native AOT.
|
||||
|
||||
For more information, see:
|
||||
|
||||
* [JSON serializer source generators](/dotnet/standard/serialization/system-text-json/source-generation)
|
||||
* [JsonSerializerOptions.TypeInfoResolverChain](https://devblogs.microsoft.com/dotnet/announcing-dotnet-8-preview-4/#jsonserializeroptions-typeinforesolverchain)
|
||||
* <xref:System.Text.Json.JsonSerializerOptions.TypeInfoResolverChain>
|
||||
|
||||
### Changes to `launchSettings.json`
|
||||
|
||||
The API template `launchSettings.json` file has the `iisSettings` section and `IIS Express` profile removed:
|
||||
|
||||
```diff
|
||||
{
|
||||
|
|
@ -230,26 +184,32 @@ The AOT version of `launchSettings.json` file is simplified and has the `iisSett
|
|||
}
|
||||
```
|
||||
|
||||
<xref:System.Text.Json.Serialization.JsonSerializerContext>:
|
||||
|
||||
* Is used in the template and shown in the preceding highlighted code.
|
||||
* Enables JSON serialization with native AOT.
|
||||
* Specifies the custom types that are needed to serialize.
|
||||
* Is used by the [JSON source generator](/dotnet/standard/serialization/system-text-json/source-generation) to produce code.
|
||||
|
||||
<a name="csb"></a>
|
||||
|
||||
<xref:Microsoft.AspNetCore.Builder.WebApplication.CreateSlimBuilder>:
|
||||
### The `CreateSlimBuilder` method
|
||||
|
||||
* Initializes the <xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder> with the minimal ASP.NET Core features necessary to run an app.
|
||||
* Is added by the template whether or not the AOT option is used.
|
||||
* By default, doesn't include support for HTTPS or HTTP/3. HTTPS and HTTP/3:
|
||||
* Typically aren't required for apps run behind a TLS termination proxy. For example, when using [TLS termination and end to end TLS with Application Gateway](/azure/application-gateway/ssl-overview).
|
||||
* Can be enabled by calling [builder.WebHost.UseQuic](xref:Microsoft.AspNetCore.Hosting.WebHostBuilderQuicExtensions.UseQuic%2A) or [builder.WebHost.UseKestrelHttpsConfiguration](https://source.dot.net/#Microsoft.AspNetCore.Server.Kestrel/WebHostBuilderKestrelExtensions.cs,fcec859000ccaa50) <!-- TODO replace with xref: (xref:Microsoft.AspNetCore.Hosting.WebHostBuilderKestrelExtensions.UseKestrel%2A) -->
|
||||
The template uses the <xref:Microsoft.AspNetCore.Builder.WebApplication.CreateSlimBuilder> method instead of the <xref:Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder> method.
|
||||
|
||||
:::code language="csharp" source="~/fundamentals/aot/samples/Program.cs" highlight="4":::
|
||||
|
||||
Because unused code is trimmed during publishing for native AOT, the app can't use unbounded reflection at runtime. Source generators are used to produce code to avoid the need for reflection. In some cases, source generators produce code optimized for AOT even when a generator is not required. To view source code that is generated based on the code in `Program.cs` add the [`<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>`](/dotnet/csharp/roslyn-sdk/source-generators-overview) property to `MyFirstAotWebApi.csproj`:
|
||||
The `CreateSlimBuilder` method initializes the <xref:Microsoft.AspNetCore.Builder.WebApplicationBuilder> with the minimum ASP.NET Core features necessary to run an app. It's used by the template whether or not the AOT option is used.
|
||||
|
||||
As noted earlier, the `CreateSlimBuilder` method doesn't include support for HTTPS or HTTP/3. These protocols typically aren't required for apps that run behind a TLS termination proxy. For example, see [TLS termination and end to end TLS with Application Gateway](/azure/application-gateway/ssl-overview). HTTPS can be enabled by calling [builder.WebHost.UseKestrelHttpsConfiguration](https://source.dot.net/#Microsoft.AspNetCore.Server.Kestrel/WebHostBuilderKestrelExtensions.cs,fcec859000ccaa50) <!-- TODO replace with xref: (xref:Microsoft.AspNetCore.Hosting.WebHostBuilderKestrelExtensions.UseKestrel%2A) --> HTTP/3 can be enabled by calling [builder.WebHost.UseQuic](xref:Microsoft.AspNetCore.Hosting.WebHostBuilderQuicExtensions.UseQuic%2A).
|
||||
|
||||
The `CreateSlimBuilder` method does include the following features needed for an efficient development experience:
|
||||
|
||||
* JSON file configuration for `appsettings.json` and `appsettings.{EnvironmentName}.json`.
|
||||
* User secrets configuration.
|
||||
* Console logging.
|
||||
* Logging configuration.
|
||||
|
||||
Including minimal features has benefits for trimming as well as AOT. For more information, see [Trim self-contained deployments and executables](/dotnet/core/deploying/trimming/trim-self-contained).
|
||||
|
||||
## Source generators
|
||||
|
||||
Because unused code is trimmed during publishing for native AOT, the app can't use unbounded reflection at runtime. [Source generators](/dotnet/csharp/roslyn-sdk/source-generators-overview) are used to produce code that avoids the need for reflection. In some cases, source generators produce code optimized for AOT even when a generator isn't required.
|
||||
|
||||
To view the source code that is generated, add the [`EmitCompilerGeneratedFiles`](/dotnet/csharp/roslyn-sdk/source-generators-overview) property to an app's `.csproj` file, as shown in the following example:
|
||||
|
||||
```xml
|
||||
<Project Sdk="Microsoft.NET.Sdk.Web">
|
||||
|
|
@ -262,62 +222,15 @@ Because unused code is trimmed during publishing for native AOT, the app can't u
|
|||
</Project>
|
||||
```
|
||||
|
||||
Run the `dotnet build` command. `publish` isn't necessary to view generated code. The built output contains an `obj/Debug/net8.0/generated/` directory and all the generated files for the project.
|
||||
Run the `dotnet build` command to see the generated code. The output includes an `obj/Debug/net8.0/generated/` directory that contains all the generated files for the project.
|
||||
|
||||
The `dotnet publish` command:
|
||||
The `dotnet publish` command also compiles the source files and generates files that are compiled. In addition, `dotnet publish` passes the generated assemblies to a native IL compiler. The IL compiler produces the native executable. The native executable contains the native machine code.
|
||||
|
||||
* Compiles the source files.
|
||||
* Generates files which are 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.
|
||||
## See also
|
||||
|
||||
## Benefits of using native AOT with ASP.NET Core
|
||||
* <xref:fundamentals/native-aot-tutorial>
|
||||
* [Native AOT deployment](/dotnet/core/deploying/native-aot/)
|
||||
|
||||
Publishing and deploying a native AOT app provides the following benefits:
|
||||
|
||||
* **Minimized disk footprint**: When publishing using native AOT a single executable is produced containing just the code from external dependencies that is used to support the program. Reduced executable size can lead to:
|
||||
* Smaller container images, for example in containerized deployment scenarios.
|
||||
* Reduced deployment time from smaller images.
|
||||
* **Reduced startup time**: Native AOT applications can show reduced start-up times. Reduced start-up means:
|
||||
* The app is ready to service requests quicker.
|
||||
* Improved deployment where container orchestrators need to manage transition from one version of the app to another.
|
||||
* **Reduced memory demand**: Native AOT apps can have reduced memory demands depending on the work being performed by the app. Reduced memory consumption can lead to greater deployment density and improved scalability.
|
||||
|
||||
The template app was run in our benchmarking lab and shows the following improvements in size, memory, and startup time:
|
||||
|
||||
|
||||
|
||||
The preceding chart shows that native AOT has significantly lower app size, memory usage, and startup time.
|
||||
|
||||
## ASP.NET Core and native AOT compatibility
|
||||
|
||||
Not all features in ASP.NET Core are currently compatible with native AOT. The following table summarizes ASP.NET Core feature compatibility with native AOT:
|
||||
|
||||
| Feature | Fully Supported | Partially Supported | Not Supported |
|
||||
| - | - | - | - |
|
||||
| gRPC | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Minimal APIs | | <span aria-hidden="true">✔️</span><span class="visually-hidden">Partially supported</span> | |
|
||||
| MVC | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| Blazor Server | | |<span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| SignalR | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| Authentication | | | <span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> (JWT soon) |
|
||||
| CORS | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| HealthChecks | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| HttpLogging | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Localization | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| OutputCaching | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| RateLimiting | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| RequestDecompression | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| ResponseCaching | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| ResponseCompression | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Rewrite | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| Session | | |<span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| Spa | | |<span aria-hidden="true">❌</span><span class="visually-hidden">Not supported</span> |
|
||||
| StaticFiles | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
| WebSockets | <span aria-hidden="true">✔️</span><span class="visually-hidden">Fully supported</span> | | |
|
||||
|
||||
It's important to test the app thoroughly when moving to a native AOT deployment model. The AOT deployed app should be tested to verify functionality hasn't changed from the untrimmed and JIT-compiled app. When building the app, review and correct AOT warnings. An app that issues AOT warnings during publishing is ***not*** guaranteed to work correctly. If no AOT warnings are issued at publish time, the published AOT app should work the same as when run in development.
|
||||
|
||||
For more information on AOT warnings and how to address them see [Introduction to AOT warnings](/dotnet/core/deploying/native-aot/fixing-warnings).
|
||||
|
||||
## Known issues
|
||||
|
||||
|
|
|
|||
|
|
@ -219,7 +219,13 @@ items:
|
|||
- name: Dependency injection (services)
|
||||
uid: fundamentals/dependency-injection
|
||||
- name: Native AOT
|
||||
uid: fundamentals/native-aot
|
||||
items:
|
||||
- name: Overview
|
||||
displayName: native, aot
|
||||
uid: fundamentals/native-aot
|
||||
- name: Tutorial
|
||||
displayName: native, aot
|
||||
uid: fundamentals/native-aot-tutorial
|
||||
- name: Middleware
|
||||
items:
|
||||
- name: Middleware overview
|
||||
|
|
|
|||
Loading…
Reference in New Issue