FreeSql 在 NativeAOT 编译环境下的使用指南

前言

随着 .NET 8 的发布，NativeAOT 编译技术越来越受到开发者关注。本文将详细介绍如何在 FreeSql 中使用 NativeAOT 编译，特别是解决 Include 和 LazyLoad 功能在 NativeAOT 环境下失效的问题。

NativeAOT 编译简介

NativeAOT（Ahead-of-Time）编译是一种将 .NET 应用程序直接编译为本机代码的技术，相比传统的 JIT 编译，它可以带来更快的启动时间和更小的内存占用。然而，这种编译方式也会带来一些限制，特别是对反射和动态代码生成的支持会受到影响。

FreeSql 在 NativeAOT 中的常见问题

1. Include 功能失效

在 NativeAOT 环境下，使用 Include 方法时可能会遇到 ArgumentNullException 异常，提示参数 property 不能为 null。这是因为 NativeAOT 在编译时会裁剪掉一些反射所需的元数据。

解决方案：

• 确保导航属性的外键字段声明为可空类型（如 long? 而不是 long）
• 添加 rd.xml 配置文件，明确告诉编译器保留必要的元数据

2. IncludeMany 功能失效

使用 IncludeMany 方法时可能会遇到 NotSupportedException，提示类型信息缺失。这是因为数组类型的元数据在 NativeAOT 编译时被裁剪了。

解决方案：

• 在程序启动时预先使用相关类型，防止被裁剪
• 确保 rd.xml 配置正确

具体配置方法

rd.xml 配置文件

创建 rd.xml 文件并添加到项目中：

<Directives>
    <Application>
        <Assembly Name="YourAssemblyName" Dynamic="Required All">
        </Assembly>
        <Assembly Name="FreeSql" Dynamic="Required All">
        </Assembly>
    </Application>
</Directives>

项目文件配置

在 .csproj 文件中添加以下配置：

<ItemGroup>
    <RdXmlFile Include="rd.xml" />
</ItemGroup>

<PropertyGroup>
    <PublishAot>true</PublishAot>
    <InvariantGlobalization>false</InvariantGlobalization>
    <TrimMode>partial</TrimMode>
</PropertyGroup>

类型预加载技巧

在程序启动时添加以下代码，确保相关类型不会被裁剪：

Console.WriteLine(typeof(long?[]));
Console.WriteLine(new long?[0].Contains((long?)1));

实体类定义建议

在 NativeAOT 环境下，实体类定义需要特别注意：

public class Company
{
    [Column(IsIdentity = true)]
    public long? Id { get; set; }  // 注意使用可空类型

    public string Name { get; set; } = string.Empty;
    public List<User> Users { get; set; } = new List<User>();
}

public class User
{
    [Column(IsIdentity = true)]
    public long Id { get; set; }

    public string Name { get; set; } = string.Empty;
    public long? CompanyId { get; set; }  // 外键使用可空类型
    public Company Company { get; set; }
}

总结

在 NativeAOT 环境下使用 FreeSql 需要注意以下几点：

1. 合理配置 rd.xml 文件
2. 实体类的外键属性建议使用可空类型
3. 对于可能被裁剪的类型，在程序启动时进行预加载
4. 避免使用 FreeSql.Extensions.LazyLoading 包

通过以上配置和注意事项，可以确保 FreeSql 在 NativeAOT 环境下正常运行，发挥 NativeAOT 编译的优势，同时保留 FreeSql 强大的 ORM 功能。