常见问题

本文档收集了在使用 Perigon.CLI 过程中可能遇到的常见问题及其解决方案。如果您在使用过程中遇到其他问题，欢迎通过 GitHub 讨论区 提出，我们将持续更新此文档以帮助更多用户。

不支持 ARM 芯片

部分苹果电脑使用 ARM 芯片，当前 Perigon.CLI 暂不支持 ARM 架构。

EF dbcontext 迁移报错

如果执行EFMigrations.ps1没有成功，请先确认已恢复 .NET 工具，并检查 Components__Database、Components__IsMultiTenant 是否与 src/AppHost/appsettings.Development.json 一致。迁移生成使用 AdminService 作为启动项目、EntityFramework 作为迁移项目；TenantIndexConvention统一处理租户索引。详细流程请参阅数据库迁移与初始化。

OpenAPI 问题

微软提供的官方 OpenAPI 一直不够完善，经历两个大版本后仍然存在诸多问题。

备注：使用 json schema 来表示 openapi 文档，本身存在一定的设计缺陷。

The depth of the generated JSON schema exceeds the JsonSerializerOptions.MaxDepth setting

这个问题通常是由实体间的相互引用导致的，并且它不会与您配置的 JsonOptions 保持一致，也没有提供任何配置项来调整。

这是一个很常见的情况，但官方 OpenAPI 库目前尚未提供理想的解决方案。

例如，实体 User 中定义了多个导航属性，而这些导航属性又引用了 User 实体，就很可能出现此报错。 详细信息可以参考：GitHub Issue。

解决方法：

1. ✅ 推荐：返回时定义新的 DTO，不要直接返回实体。
2. ⚠️ 不推荐：在关联属性上添加 [JsonIgnore] 属性，避免 JSON 解析时的循环引用。
3. ⏳ 等待官方库修复。

不支持 XML 注释

在 .NET 10 中已经添加了对 XML 注释的支持，但存在一些限制。

1. 您必须在 WebAPI 项目中调用 services.AddOpenApi 来注入服务，因为使用了源代码生成器。这意味着您不能在其他程序集中复用，需要在每个 WebAPI 项目中都添加一遍。

2. 您必须在 WebAPI 项目中引用 OpenAPI 包依赖，不可在其他程序集中引用，否则可能会报错，或无法正常生成相关的 XML 注释。

生成错误的请求服务

由于请求服务是通过读取 OpenAPI 文档来生成的，而 OpenAPI 可能在某些情况下生成不符合预期的内容，导致生成的请求服务代码有问题。

解决方法：

1. 到官方仓库提交 Issue，等待修复。

不使用 Aspire

如果您只有一两个服务，基础设施也是现有的，那么完全可以不使用 Aspire。您需要进行以下调整：

• 移除 AppHost 项目
• 移除 ServiceDefaults 项目
• ApiStandard 可移除 AppHost/ServiceDefaults，并在部署管线中按标准方式管理 EF 迁移；MiniApi 本身不包含内置迁移资源
• 在服务中移除 ServiceDefaults 依赖
• 在服务中按照 ASP.NET Core 的标准方式来配置连接字符串等内容