Orleans source generation

Orleans generates grain proxies, method dispatch code, serializers, and copiers at build time. There is no runtime or initialization-time code generation workflow for application code.

Reference the SDK

Use the package matching the project role:

• Microsoft.Orleans.Client for client applications.
• Microsoft.Orleans.Server for silo applications.
• Microsoft.Orleans.Sdk for class libraries containing grain contracts, implementations, or serializable types.

These packages include the source generator and analyzers.

Grain contracts

The generator discovers grain interfaces and implementations from their Orleans base interfaces. It reports build diagnostics for unsupported signatures, inaccessible types, multiple cancellation token parameters, and other contract errors.

Supported grain method return types are Task, Task<T>, ValueTask, and ValueTask<T>. The generator emits strongly typed references and invocation classes for those methods.

Serializable types

Mark application data crossing grain boundaries or stored by Orleans with GenerateSerializerAttribute. Give serialized members stable field IDs:

[GenerateSerializer]
public sealed class PurchaseOrder
{
    [Id(0)]
    public required string OrderId { get; init; }

    [Id(1)]
    public decimal Total { get; init; }
}

IDs are part of the wire and storage contract. Don’t reuse or renumber them after deployment. Use AliasAttribute when a stable serialized type alias is required independently of the CLR name.

Generate code for external types

When a project must generate serializers for accessible types declared elsewhere, use GenerateCodeForDeclaringAssemblyAttribute:

[assembly: GenerateCodeForDeclaringAssembly(
    typeof(ExternalContract))]

Prefer owning serialization annotations with the type whenever possible. Generating for external declaring assemblies broadens the compatibility surface and can increase build output.

Other .NET languages

For end-to-end interop examples, see the Orleans F# sample and Orleans Visual Basic sample.

Inspect diagnostics and output

Treat Orleans analyzer and generator diagnostics as contract errors, not warnings to suppress. Generated files can be inspected through normal compiler-generated-file tooling when debugging, but application code should depend on the public interfaces rather than generated implementation names.

The optional Orleans contract compatibility analyzer records grain RPC identities and signatures in OrleansContracts.txt so contract drift can be reviewed before a rolling upgrade.

For serialization rules and version tolerance, see Orleans serialization.