This document collects common questions and solutions when using Perigon.CLI. If you encounter other issues, please use the GitHub Discussions so we can continue improving this guide.
Some Apple computers use ARM chips; Perigon.CLI does not currently support ARM.
Microsoft’s official OpenAPI packages are still maturing, even after two major iterations. Note that describing OpenAPI with JSON Schema has inherent limitations.
This usually stems from entity circular references. It does not honor your JsonOptions and exposes no configuration to adjust the limit. This is common, and the official OpenAPI library doesn’t yet provide an ideal solution. For example, User may have navigation properties that in turn reference User, causing this error. See the related GitHub issue.
Recommended mitigations:
[JsonIgnore] on navigation properties to break cycles at serialization time.Tip
Prefer returning DTOs rather than entities.
.NET 10 added XML comment support with some constraints:
services.AddOpenApi in each Web API project (uses a source generator). You cannot centralize this setup in a separate assembly.Clients are generated from the OpenAPI document. If the document is incorrect, the generated clients will be too.
Suggested actions:
Important
The template uses Swashbuckle.AspNetCore for OpenAPI and includes extensions to improve document quality and better support code generators.
If you only have a couple of services and already have infrastructure, you can skip Aspire. Adjust as follows:
MigrationsService and manage EF migrations traditionally.This document collects common problems and solutions that may be encountered when using Perigon.CLI. If you encounter other issues during use, please feel free to raise them through the GitHub Discussions. We will continuously update this document to help more users.
Some Apple computers use ARM chips. Currently, Perigon.CLI does not support ARM architecture.
The official OpenAPI provided by Microsoft has not been fully developed, and there are still many issues after two major versions.
Note: Using json schema to represent openapi documents has inherent design flaws.
This issue is usually caused by circular references between entities, and it does not align with the JsonOptions you configure, nor does it provide any configuration options to adjust it.
This is a common situation, but the official OpenAPI library has not yet provided an ideal solution.
For example, if the User entity defines multiple navigation properties, and these navigation properties reference the User entity again, this error is likely to occur.
For more details, please refer to: GitHub Issue.
Solutions:
DTO when returning data, and don't return entities directly.[JsonIgnore] attribute to related properties to avoid circular references during JSON parsing.Tip
It is recommended not to return entities directly, but to return data through defined DTOs.
In .NET 10, support for XML comments has been added, but there are some limitations.
You must call services.AddOpenApi in the WebAPI project to inject the service because it uses a source code generator. This means you cannot reuse it in other assemblies and need to add it in every WebAPI project.
You must reference the OpenAPI package dependency in the WebAPI project, and it cannot be referenced in other assemblies, otherwise it may cause errors or fail to generate related XML comments properly.
Since request services are generated by reading OpenAPI documents, and OpenAPI may sometimes generate content that doesn't meet expectations, this can lead to issues with the generated request service code.
Solutions:
Important
The template itself uses Swashbuckle.AspNetCore to generate OpenAPI documents and provides some extension features to enhance the quality of generated documents, better supporting code generator usage.
If you only have one or two services and the infrastructure is already existing, you can completely avoid using Aspire. You need to make the following adjustments:
MigrationsService project and manage database migrations in the traditional wayASP.NET Core approach