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.

Hot Reload for serializable members

Enable the Hot Reload generation shape in development builds:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <OrleansHotReload>true</OrleansHotReload>
</PropertyGroup>

The generator gives serializer and copier fields stable identities and resolves newly added concrete codec and copier dependencies when an existing generated instance first uses them. A running application can therefore apply supported .NET Hot Reload updates which add strongly typed [Id] members to [GenerateSerializer] classes and records, including members whose concrete serializable type is added in the same update.

Keep each [Id] value stable and unique. Additive member updates preserve the existing wire contract. Changes to existing member types, IDs, type hierarchy, generic shape, grain interfaces, and generated invokable types follow the corresponding .NET Hot Reload and Orleans contract compatibility requirements. A restart rebuilds the serializer manifest after updates which introduce new types through polymorphic declarations such as object or interfaces, or through container element types.

When OrleansHotReload is unset or false, the generator emits readonly fields with eager initialization for normal application builds.

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.

Libraries which define custom grain-call return types can extend the generated proxy and invokable request model. See Customize Orleans serialization code generation.

For serialization rules and version tolerance, see Orleans serialization.