FastEndpoints.Generator.Cli

A .NET CLI tool for generating JSON serializer contexts for FastEndpoints applications. This tool analyzes your FastEndpoints projects and generates optimized System.Text.Json serializer contexts for improved performance through source generation.

Installation

As a Global Tool (Recommended)

bash

dotnet tool install --global FastEndpoints.Generator.Cli

Install a Specific Version

bash

dotnet tool install --global FastEndpoints.Generator.Cli --version 8.0.0

Update to Latest Version

bash

dotnet tool update --global FastEndpoints.Generator.Cli

Usage

Basic Usage

Generate serializer contexts for a project:

bash

fastendpoints-generator MyProject.csproj

With Custom Output Path

Specify a custom output directory for generated files:

bash

fastendpoints-generator MyProject.csproj --output Generated/FastEndpoints

Force Regeneration

Force regeneration even if files are up to date:

bash

fastendpoints-generator MyProject.csproj --force

Full Options

bash

fastendpoints-generator <project-file-path> [--force] [--output <path>]

Options:
  --force         Force regeneration even if files are up to date
  --output <path> Custom output path for generated files

What It Generates

The tool analyzes your FastEndpoints classes and generates:

SerializerContexts.g.cs - A partial JsonSerializerContext class with [JsonSerializable] attributes for all types used in your endpoints (requests, responses, and their dependencies).
SerializerContextExtensions.g.cs - Extension methods for JsonSerializerOptions to easily register the generated context.

Example Output

After running the tool, you'll see output like:

Analyzing project: MyProject
Found 42 source files.
Found 15 type declarations.
Found 8 endpoints with 12 serializable types.
  Found endpoint: MyProject.Features.Users.GetUserEndpoint
  Found endpoint: MyProject.Features.Users.CreateUserEndpoint
  ...
Generated files:
  Generated/FastEndpoints/SerializerContexts.g.cs
  Generated/FastEndpoints/SerializerContextExtensions.g.cs

Integration with MSBuild

The FastEndpoints.Generator package includes MSBuild targets that automatically install and run this tool during build. To enable automatic generation:

Add the FastEndpoints.Generator package to your project:

bash

dotnet add package FastEndpoints.Generator

Set the property in your .csproj:

xml

<PropertyGroup>
    <GenerateSerializerContexts>true</GenerateSerializerContexts>
</PropertyGroup>

Optionally customize the output path:

xml

<PropertyGroup>
    <SerializerContextOutputPath>Generated/FastEndpoints</SerializerContextOutputPath>
</PropertyGroup>

The tool will be automatically installed/updated on the first build and will generate the serializer contexts before compilation.

Using the Generated Code

In your application startup, use the extension method to register the serializer context. The method returns the same JsonSerializerOptions instance so calls can be chained across multiple projects:

csharp

using System.Text.Json;

var options = new JsonSerializerOptions
{
    // Your options
}.AddSerializerContextsFromMyProject();  // Extension method generated by the tool

// Use with FastEndpoints
app.UseFastEndpoints(c =>
{
    c.Serializer.Options.AddSerializerContextsFromMyProject();  // Extension method generated by the tool
});

// Chain contexts from referenced projects
options.AddSerializerContextsFromFeatureA()
       .AddSerializerContextsFromMyProject();

Or manually register the context:

csharp

var context = new GeneratedSerializerContext(new JsonSerializerOptions());
options.TypeInfoResolverChain.Insert(0, context);

How It Works

Endpoint Discovery: The tool scans your project for classes that inherit from FastEndpoints base classes (Endpoint, EndpointWithoutRequest, EndpointWithMapper, etc.).
Type Analysis: For each endpoint, it analyzes the generic type arguments to identify request and response types.
Dependency Resolution: It recursively analyzes the properties of each type to find all types that need serialization.
Smart Filtering: Built-in filtering excludes system types, framework types, and types that don't need serialization.
Incremental Generation: The tool uses a cache file (.fastendpoints-generator-cache) to avoid unnecessary regeneration when source files haven't changed.

Type Filtering

The tool automatically excludes:

System namespaces (System, Microsoft, etc.)
Framework namespaces (FastEndpoints, FluentValidation, etc.)
Infrastructure types (EmptyRequest, EmptyResponse)
Types with certain base classes (Mapper, Validator, etc.)

Requirements

.NET 8.0 or later
A project that uses FastEndpoints

Troubleshooting

Tool Not Found

If you get "command not found" after installation, ensure the global tools directory is in your PATH:

bash

# Windows (PowerShell)
$env:PATH += ";$env:USERPROFILE\.dotnet\tools"

# Linux/macOS
export PATH="$PATH:$HOME/.dotnet/tools"

Generation Not Working

Ensure your project compiles without errors
Check that your endpoints properly inherit from FastEndpoints base classes
Use --force to bypass the cache and force regeneration
Verify the tool version matches your FastEndpoints version