Table of Contents

Getting Started

This guide covers the installation and basic setup of the Cratis Arc proxy generator.

Package Dependency

To enable proxy generation, add a reference to the Cratis.Arc.ProxyGenerator.Build NuGet package to your project:

<PackageReference Include="Cratis.Arc.ProxyGenerator.Build" Version="1.0.0" />

Important: All projects that contain controllers, commands, or queries should reference this package, as the proxy generation runs as part of the compilation process.

Required Configuration

Configure the proxy generator by adding MSBuild properties to your .csproj file:

<PropertyGroup>
    <CratisProxiesOutputPath>$(MSBuildThisFileDirectory)../Web</CratisProxiesOutputPath>
</PropertyGroup>
  • CratisProxiesOutputPath: Specifies where the generated TypeScript files will be written. This should typically point to your frontend project directory.

Note: By default, the proxy generator deletes the entire output directory on every build to ensure clean generation. If your proxies are intertwined with other source files (not in a dedicated folder), you should set <CratisProxiesSkipOutputDeletion>true</CratisProxiesSkipOutputDeletion> to enable incremental generation. See Configuration - Output Deletion Behavior for details.

Frontend Prerequisites

The generated proxies depend on the @cratis/arc NPM package. Install it in your frontend project:

npm install @cratis/arc

Build Integration

The proxy generation runs automatically during the build process. Simply build your project:

dotnet build

The generator will:

  1. Load your compiled assembly
  2. Discover controllers, commands, and queries
  3. Analyze parameter types and return values
  4. Generate TypeScript proxies with proper typing
  5. Create index files for easy importing
  6. Maintain the folder structure based on namespaces

What Gets Generated

The proxy generator creates TypeScript proxies for:

  • Commands: Both controller-based and model-bound approaches. See Commands documentation for implementation details.
  • Queries: Single model, enumerable, and observable queries. See Queries documentation for implementation details.
  • Types: Complex types used as parameters or return values
  • Enums: Enumerations referenced by commands or queries
  • Identity Details: Types from IProvideIdentityDetails<TDetails> implementations

Next Steps