ApiStandard Quick Start

ApiStandard targets conventional ASP.NET Core Web APIs and modular business systems. It includes EF Core, an Aspire migration resource, AdminService, and ApiService.

ApiStandard uses Aspire 13.6.1; install a matching Aspire CLI before running AppHost.

Create a project

dotnet new install Perigon.templates --version 1.3.17
dotnet new perigon-webapi -n MyWebApi --frontType None
cd MyWebApi

Use --frontType Angular when an Angular frontend is required, then run pnpm install in src/ClientApp/WebApp. The template does not generate or start the frontend by default; the optional frontend resource in AppHost must also be enabled.

Configure database and cache

Configure the Components node in src/AppHost/appsettings.Development.json:

{
  "Components": {
    "Cache": "Memory",
    "Database": "PostgreSQL",
    "IsMultiTenant": true
  }
}

Database supports PostgreSQL and SqlServer. Cache supports Memory, Redis, and Hybrid. AppHost creates Redis only for Redis or Hybrid and passes the selected value to services through Components__Cache.

ApiStandard enables multi-tenancy by default. Authenticated requests must carry a valid TenantId; database initialization creates default.com and stores the default business and analysis database connection strings. Missing, invalid, or unknown tenants do not silently fall back to the default tenant or connection.

See Template Configuration Reference for Components, authentication, cache, login policy, SMTP, SMS, S3, and environment-variable settings.

Create migrations and run

Standard uses EF Core migrations. After creating a project or changing entities:

.\scripts\EFMigrations.ps1 Init
aspire start --non-interactive

AppHost creates the AdminService-Migrations migration resource. During local runs, RunDatabaseUpdateOnStart() applies the migrations before AdminService and ApiService start. For Kubernetes publishing, it generates a one-shot migration Job. The migration script uses AdminService as the startup project, Components__Database selects the provider, and TenantIndexConvention handles tenant indexes.

See EF Core migrations and seeding and Deploying Applications for migrations, UseSeeding/UseAsyncSeeding, and Kubernetes publishing. The default template does not include SystemMod, so it does not create a login-ready administrator account. If the module is installed, follow its initialization guide and never reuse example credentials in production.

OpenAPI and tests

Standard uses Swashbuckle and exposes the OpenAPI JSON document at:

/swagger/v1/swagger.json

Non-production environments also expose Swagger UI at:

/swagger

Unit tests do not start Aspire:

dotnet test --project tests/UnitTest/UnitTest.csproj

Run Aspire integration tests only when real infrastructure and multiple services are needed:

dotnet test --project tests/ApiTest/ApiTest.csproj --treenode-filter '/*/*/*/*[Category=Integration]'

Integration tests require Docker/Podman. See the Production Operations Runbook for migration failures, health checks, and log tracing.

The template does not create an administrator account by default. If SystemMod is installed and authenticated tests are enabled, provide the test account through PERIGON_TEST_ADMIN_EMAIL and PERIGON_TEST_ADMIN_PASSWORD environment variables.