Documentation for NativeAOT/precompiled queries (#4868)

Closes #3988

entity-framework/core/performance/nativeaot-and-precompiled-queries.md

@@ -0,0 +1,110 @@
+---
+title: NativeAOT Support and Precompiled Queries (Experimental) - EF Core
+description: Publishing NativeAOT Entity Framework Core applications and using precompiled queries
+author: roji
+ms.date: 11/10/2024
+uid: core/performance/nativeaot-and-precompiled-queries
+---
+# NativeAOT Support and Precompiled Queries (Experimental)
+
+> [!WARNING]
+> NativeAOT and query precompilation are highly experimental feature, and are not yet suited for production use. The support described below should be viewed as infrastructure towards the final feature, which will likely be released with EF 10. We encourage you to experiment with the current support and report on your experiences, but recommend against deploying EF NativeAOT applications in production. See below for specific known limitations.
+
+[.NET NativeAOT](/dotnet/core/deploying/native-aot) allows publishing self-contained .NET applications that have been compiled ahead-of-time (AOT). Doing so offers the following advantages:
+
+* Significantly faster application startup time
+* Small, self-contained binaries that have smaller memory footprints and are easier to deploy
+* Running applications in environments where just-in-time compilation isn't supported
+
+EF applications published with NativeAOT start up much faster than the same applications without it. In addition to the general .NET startup improvements that NativeAOT offers (i.e. no JIT compilation required each time), EF also precompiles LINQ queries when publishing your application, so that no processing is needed when starting up and the SQL is already available for immediate execution. The more EF LINQ queries an application has in its code, the faster the startup gains are expected to be.
+
+## Publishing an EF NativeAOT Application
+
+First, enable NativeAOT publishing for your project as follows:
+
+```xml
+<PropertyGroup>
+    <PublishAot>true</PublishAot>
+</PropertyGroup>
+```
+
+EF's support for LINQ query execution under NativeAOT relies on *query precompilation*: this mechanism statically identifies EF LINQ queries and generates C# [*interceptors*](/dotnet/csharp/whats-new/csharp-12#interceptors), which contain code to execute each specific query. This can significantly cut down on your application's startup time, as the heavy lifting of processing and compiling your LINQ queries into SQL no longer happens every time your application starts up. Instead, each query's interceptor contains the finalized SQL for that query, as well as optimized code to materialize database results as .NET objects.
+
+C# interceptors are currently an experimental feature, and require a special opt-in in your project file:
+
+```xml
+<PropertyGroup>
+  <InterceptorsNamespaces>$(InterceptorsPreviewNamespaces);Microsoft.EntityFrameworkCore.GeneratedInterceptors</InterceptorsNamespaces>
+</PropertyGroup>
+```
+
+Finally, the [`Microsoft.EntityFrameworkCore.Tasks`](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore.Tasks) package contains MSBuild integration that will perform the query precompilation (and generate the required compiled model) when you publish your application:
+
+```xml
+<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="..." />
+```
+
+You're now ready to publish your EF NativeAOT application:
+
+```console
+dotnet publish -r linux-arm64 -c Release
+```
+
+This shows publishing a NativeAOT publishing for Linux running on ARM64; [consult this catalog](/dotnet/core/rid-catalog) to find your runtime identifier. If you'd like to generate the interceptors without publishing - for example to examine the generated sources - you can do so via the `net ef dbcontext optimize --precompile-queries --nativeaot` command.
+
+Due to the way C# interceptors work, any change in the application source invalidates them and requires repeating the above process. As a result, interceptor generation and actual publishing aren't expected to happen in the inner loop, as the developer is working on code; instead, both `dotnet ef dbcontext optimize` and `dotnet publish` can be executed in a publishing/deployment workflow, in a CI/CD system.
+
+> [!NOTE]
+> Publishing currently reports a number of trimming and NativeAOT warnings, meaning that your application isn't fully guaranteed to run properly. This is expected given the current experimental state of NativeAOT support; the final, non-experimental feature will report no warnings.
+
+## Limitations
+
+### Dynamic queries are not supported
+
+Query precompilation performs static analysis of your source code, identifying EF LINQ queries and generating C# interceptors for them. LINQ allows expressing highly dynamic queries, where LINQ operators are composed based on arbitrary conditions; such queries unfortunately cannot be statically analyzed, and are currently unsupported. Consider the following example:
+
+```c#
+IAsyncEnumerable<Blog> GetBlogs(BlogContext context, bool applyFilter)
+{
+    IQueryable<Blog> query = context.Blogs.OrderBy(b => b.Id);
+
+    if (applyFilter)
+    {
+        query = query.Where(b => b.Name != "foo");
+    }
+
+    return query.AsAsyncEnumerable();
+}
+```
+
+The above query is split across several statements, and dynamically composes the `Where` operator based on an external parameter; such queries cannot be precompiled. However, it is sometimes possible to rewrite such dynamic queries as multiple non-dynamic queries:
+
+```c#
+IAsyncEnumerable<Blog> GetBlogs(BlogContext context, bool applyFilter)
+    => applyFilter
+        ? context.Blogs.OrderBy(b => b.Id).Where(b => b.Name != "foo").AsAsyncEnumerable()
+        : context.Blogs.OrderBy(b => b.Id).AsAsyncEnumerable();
+```
+
+Since the two queries can each be statically analyzed from start to finish, precompilation can handle them.
+
+Note that dynamic queries will likely be supported in the future when using NativeAOT; however, since they cannot be precompiled, they will continue to slow down your application startup, and will also generally perform less efficiently compared to non-NativeAOT execution; this is because EF internally relies on code generation to materialize database results, but code generation is not supported when using NativeAOT.
+
+### Other limitations
+
+* LINQ query expression syntax (sometimes termed "comprehension syntax") is not supported.
+* The generated compiled model and query interceptors may currently be quite large in terms of code size, and take a long while to generate. We plan on improving this.
+* EF providers may need to build in support for precompiled queries; check your provider's documentation to know whether it is compatible with EF's NativeAOT support.
+* Value converters that use captured state are not supported.
+
+## Precompiled queries without NativeAOT
+
+Because of the current limitations of EF's NativeAOT support, it may not be usable for some applications. However, you may be able to take advantage of precompiled queries while publishing regular, non-NativeAOT applications; this allows you to at least benefit from the startup time reduction that precompiled queries offer, while being able to use dynamic queries and other features not currently supported with NativeAOT.
+
+Using precompiled queries without NativeAOT is simply a matter of executing the following:
+
+```console
+dotnet ef dbcontext optimize --precompile-queries
+```
+
+As shown above, this will generate a compiled model and interceptors for queries which could be precompiled, removing their overhead from your application's startup time.

entity-framework/core/what-is-new/ef-core-9.0/whatsnew.md

@@ -296,21 +296,36 @@ Note, however, that we plan to fully remove sync support in EF 11, so start upda
 
 ## AOT and pre-compiled queries
 
-As mentioned in the introduction, there is a lot of work going on behind the scenes to allow EF Core to run without just-in-time (JIT) compilation. Instead, EF compile ahead-of-time (AOT) everything needed to run queries in the application. This AOT compilation and related processing will happen as part of building and publishing the application. At this point in the EF9 release, there is not much available that can be used by you, the app developer. However, for those interested, the completed issues in EF9 that support AOT and pre-compiled queries are:
-
-* [Compiled model: Use static binding instead of reflection for properties and fields](https://github.com/dotnet/efcore/issues/24900)
-* [Compiled model: Generate lambdas used in change tracking](https://github.com/dotnet/efcore/issues/24904)
-* [Make change tracking and the update pipeline compatible with AOT/trimming](https://github.com/dotnet/efcore/issues/29761)
-* [Use interceptors to redirect the query to precompiled code](https://github.com/dotnet/efcore/issues/31331)
-* [Make all SQL expression nodes quotable](https://github.com/dotnet/efcore/issues/33008)
-* [Generate the compiled model during build](https://github.com/dotnet/efcore/issues/24894)
-* [Discover the compiled model automatically](https://github.com/dotnet/efcore/issues/24893)
-* [Make ParameterExtractingExpressionVisitor capable of extracting paths to evaluatable fragments in the tree](https://github.com/dotnet/efcore/issues/32999)
-* [Generate expression trees in compiled models (query filters, value converters)](https://github.com/dotnet/efcore/issues/29924)
-* [Make LinqToCSharpSyntaxTranslator more resilient to multiple declaration of the same variable in nested scopes](https://github.com/dotnet/efcore/issues/32716)
-* [Optimize ParameterExtractingExpressionVisitor](https://github.com/dotnet/efcore/issues/32698)
-
-Check back here for examples of how to use pre-compiled queries as the experience comes together.
+> [!WARNING]
+> NativeAOT and query precompilation are highly experimental features, and are not yet suited for production use. The support described below should be viewed as infrastructure towards the final feature, which will likely be released with EF 10. We encourage you to experiment with the current support and report on your experiences, but recommend against deploying EF NativeAOT applications in production.
+
+EF 9.0 brings initial, experimental support for [.NET NativeAOT](/dotnet/core/deploying/native-aot), allowing the publishing of ahead-of-time compiled applications which make use of EF to access databases. To support LINQ queries in NativeAOT mode, EF relies on _query precompilation_: this mechanism statically identifies EF LINQ queries and generates C# [_interceptors_](/dotnet/csharp/whats-new/csharp-12#interceptors), which contain code to execute each specific query. This can significantly cut down on your application's startup time, as the heavy lifting of processing and compiling your LINQ queries into SQL no longer happens every time your application starts up. Instead, each query's interceptor contains the finalized SQL for that query, as well as optimized code to materialize database results as .NET objects.
+
+For example, given a program with the following EF query:
+
+```c#
+var blogs = await context.Blogs.Where(b => b.Name == "foo").ToListAsync();
+```
+
+EF will generate a C# interceptor into your project, which will take over the query execution. Instead of processing the query and translating it to SQL every time the program starts, the interceptor has the SQL embedded right into it (for SQL Server in this case), allowing your program to start up much faster:
+
+```c#
+var relationalCommandTemplate = ((IRelationalCommandTemplate)(new RelationalCommand(materializerLiftableConstantContext.CommandBuilderDependencies, "SELECT [b].[Id], [b].[Name]\nFROM [Blogs] AS [b]\nWHERE [b].[Name] = N'foo'", new IRelationalParameter[] { })));
+```
+
+In addition, the same interceptor contains code to materialize your .NET object from database results:
+
+```c#
+var instance = new Blog();
+UnsafeAccessor_Blog_Id_Set(instance) = dataReader.GetInt32(0);
+UnsafeAccessor_Blog_Name_Set(instance) = dataReader.GetString(1);
+```
+
+This uses another new .NET feature - [unsafe accessors](/dotnet/api/system.runtime.compilerservices.unsafeaccessorattribute), to inject data from the database into your object's private fields.
+
+If you're interested in NativeAOT and like to experiment with cutting-edge features, give this a try! Just be aware that the feature should be considered unstable, and currently has many limitations; we expect to stabilize it and make it more suitable for production usage in EF 10.
+
+See the [NativeAOT documentation page](xref:core/performance/nativeaot-and-precompiled-queries) for more details.
 
 ## LINQ and SQL translation
 

entity-framework/toc.yml

@@ -350,6 +350,8 @@
         href: core/performance/efficient-updating.md
       - name: Modeling for performance
         href: core/performance/modeling-for-performance.md
+      - name: NativeAOT and precompiled queries
+        href: core/performance/nativeaot-and-precompiled-queries.md
       - name: Advanced performance topics
         href: core/performance/advanced-performance-topics.md
 
@@ -361,7 +363,6 @@
         href: core/miscellaneous/async.md
       - name: Nullable reference types
         href: core/miscellaneous/nullable-reference-types.md
-      #- name: Using dependency injection
       - name: Collations and case sensitivity
         href: core/miscellaneous/collations-and-case-sensitivity.md
       - name: Connection resiliency