fix(codegen): harden hot reload generation

Author: ReubenBond

docs/site/src/content/docs/grains/code-generation.md

@@ -1,7 +1,7 @@
 ---
 title: Orleans source generation
 description: Understand build-time code generation for grains and serialization in Orleans.
-ms.date: 08/07/2026
+ms.date: 09/01/2026
 ms.topic: concept-article
 ---
 
@@ -32,6 +32,22 @@ Mark application data crossing grain boundaries or stored by Orleans with <xref:
 :::code language="csharp" source="../snippets/compiled/Grains/GeneralSnippets.cs" id="serializable_purchase_order":::
 IDs are part of the wire and storage contract. Don't reuse or renumber them after deployment. Use <xref:Orleans.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:
+
+```xml
+<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 <xref:Orleans.GenerateCodeForDeclaringAssemblyAttribute>:

src/Orleans.CodeGenerator/GeneratedSourceOutput.cs

@@ -302,8 +302,8 @@ internal static string CreateHintNameHash(
         return CreateStableHash(builder.ToString());
     }
 
-    internal static string CreateStableHash(string value)
-        => HexConverter.ToString(XxHash32.Hash(Encoding.UTF8.GetBytes(value ?? string.Empty)));
+    internal static string CreateStableHash(string value, int seed = 0)
+        => HexConverter.ToString(XxHash32.Hash(Encoding.UTF8.GetBytes(value ?? string.Empty), seed));
 
     internal static void AppendHashComponent(StringBuilder builder, string value)
     {
@@ -379,4 +379,3 @@ internal static string SanitizeHintComponent(string value)
         return result.Length > 0 ? result : "generated";
     }
 }
-

src/Orleans.CodeGenerator/ProxySourceOutputGenerator.cs

@@ -17,7 +17,7 @@ internal static SourceOutputResult CreateProxySourceOutput(
         try
         {
             SourceGeneratorOptionsParser.AttachDebuggerIfRequested(options);
-            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options, compilation);
+            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options);
             var generatorServices = new GeneratorServices(compilation, codeGeneratorOptions);
             var proxyContext = new ProxyGenerationContext(compilation, codeGeneratorOptions);
             var model = proxyOutputModel.ProxyInterface;
@@ -187,7 +187,7 @@ internal static ProxyOutputPreparationResult CreateProxyOutputPreparation(
                     []);
             }
 
-            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options, compilation);
+            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options);
             var libraryTypes = LibraryTypes.FromCompilation(compilation, codeGeneratorOptions);
             var generatorServices = new GeneratorServices(compilation, codeGeneratorOptions, libraryTypes);
             var proxyContext = new ProxyGenerationContext(compilation, codeGeneratorOptions, libraryTypes);

src/Orleans.CodeGenerator/ReferenceAssemblyDataProvider.cs

@@ -14,7 +14,7 @@ internal static ReferenceAssemblyDataResult CreateReferenceAssemblyDataResult(
         {
             var model = ModelExtractor.ExtractReferenceAssemblyData(
                 compilation,
-                SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options, compilation),
+                SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options),
                 cancellationToken,
                 out var diagnostics);
 

src/Orleans.CodeGenerator/SerializableSourceOutputGenerator.cs

@@ -29,7 +29,7 @@ internal static SerializableTypeResult CreateSerializableTypeResult(
             SourceGeneratorOptionsParser.AttachDebuggerIfRequested(options);
 
             var compilation = context.SemanticModel.Compilation;
-            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options, compilation);
+            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options);
             var libraryTypes = LibraryTypes.FromCompilation(compilation, codeGeneratorOptions);
             var typeDescription = CreateSerializableTypeDescription(compilation, libraryTypes, codeGeneratorOptions, symbol);
             if (typeDescription is null)
@@ -66,7 +66,7 @@ internal static ImmutableArray<SourceOutputResult> CreateSerializableSourceOutpu
         }
 
         SourceGeneratorOptionsParser.AttachDebuggerIfRequested(options);
-        var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options, compilation);
+        var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options);
         var generatorServices = new GeneratorServices(compilation, codeGeneratorOptions);
         var resolver = new TypeSymbolResolver(compilation);
         var assemblyName = compilation.AssemblyName ?? "assembly";
@@ -162,7 +162,7 @@ internal static ImmutableArray<SourceOutputResult> CreateReferencedSerializableS
             }
 
             SourceGeneratorOptionsParser.AttachDebuggerIfRequested(options);
-            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options, compilation);
+            var codeGeneratorOptions = SourceGeneratorOptionsParser.CreateCodeGeneratorOptions(options);
             var generatorServices = new GeneratorServices(compilation, codeGeneratorOptions);
             var resolver = new TypeSymbolResolver(compilation);
             var assemblyName = compilation.AssemblyName ?? "assembly";
@@ -470,4 +470,3 @@ internal static bool IsCurrentCompilationAssembly(TypeMetadataIdentity metadataI
 }
 
 
-

src/Orleans.CodeGenerator/SourceGeneratorOptionsParser.cs

@@ -1,5 +1,4 @@
 using System.Diagnostics;
-using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.Diagnostics;
 using Orleans.CodeGenerator.Model;
 
@@ -9,13 +8,13 @@ internal static class SourceGeneratorOptionsParser
 {
     private static int _debuggerLaunchState;
 
-    internal static CodeGeneratorOptions CreateCodeGeneratorOptions(SourceGeneratorOptions options, Compilation compilation)
+    internal static CodeGeneratorOptions CreateCodeGeneratorOptions(SourceGeneratorOptions options)
     {
         return new CodeGeneratorOptions
         {
             GenerateFieldIds = options.GenerateFieldIds,
             GenerateCompatibilityInvokers = options.GenerateCompatibilityInvokers,
-            HotReloadSafe = options.HotReload ?? compilation.Options.OptimizationLevel == OptimizationLevel.Debug,
+            HotReloadSafe = options.HotReload ?? false,
         };
     }
 
@@ -54,7 +53,7 @@ internal static SourceGeneratorOptions ParseOptions(AnalyzerConfigOptions global
             result.GenerateCompatibilityInvokers = genCompatInvokers;
         }
 
-        if (globalOptions.TryGetValue("build_property.orleans_hotreload", out var hotReloadValue)
+        if (globalOptions.TryGetValue("build_property.orleanshotreload", out var hotReloadValue)
             && bool.TryParse(hotReloadValue, out var hotReload))
         {
             result.HotReload = hotReload;
@@ -72,7 +71,7 @@ internal struct SourceGeneratorOptions : IEquatable<SourceGeneratorOptions>
     public bool AttachDebugger { get; set; }
 
     /// <summary>
-    /// Forces hot-reload-safe code generation on or off; when unset, it follows the compilation's optimization level.
+    /// Enables hot-reload-safe code generation.
     /// </summary>
     public bool? HotReload { get; set; }
 

src/Orleans.CodeGenerator/SyntaxGeneration/GeneratedFieldNames.cs

@@ -3,58 +3,26 @@
 namespace Orleans.CodeGenerator.SyntaxGeneration;
 
 /// <summary>
-/// Produces names for generated private fields which are stable under member reordering and most member additions,
-/// so that .NET Hot Reload sees additions rather than retyped or renamed fields. Adding a member whose type causes
-/// a previously unseen name collision may still force existing names to switch to a hash-suffixed form.
+/// Produces names for generated private fields which are stable under member reordering and additions,
+/// so that .NET Hot Reload sees additions rather than retyped or renamed fields.
 /// </summary>
 internal static class GeneratedFieldNames
 {
+    private const int SecondaryHashSeed = unchecked((int)0x9E3779B9);
+
     public static string Accessor(string prefix, IMemberDescription member)
         => member.IsPrimaryConstructorParameter ? $"{prefix}_{member.FieldId}_ctor" : $"{prefix}_{member.FieldId}";
 
     public static string[] ForTypes(string prefix, IReadOnlyList<IMemberDescription> members)
     {
-        if (members.Count == 0)
-        {
-            return [];
-        }
-
-        // phase 0: optimistic pass: try to get a readable name for each type, and see if any collide
         var result = new string[members.Count];
         for (var i = 0; i < members.Count; i++)
         {
-            result[i] = TryGetTypeKey(members[i].Type) is { } key ? $"{prefix}_{key}" : null!;
-        }
-
-        // phase 1: detect collisions and mark them for hashing
-        Span<bool> contested = members.Count <= 64 ? stackalloc bool[members.Count] : new bool[members.Count];
-        contested.Clear();
-        for (var i = 0; i < members.Count; i++)
-        {
-            // we couldn't get a readable name for this type, so we need to hash it
-            if (result[i] is null)
-            {
-                contested[i] = true;
-                continue;
-            }
-
-            for (var j = i + 1; j < members.Count; j++)
-            {
-                if (string.Equals(result[i], result[j], StringComparison.Ordinal))
-                {
-                    contested[i] = true;
-                    contested[j] = true;
-                }
-            }
-        }
-
-        // phase 2: for any contested names, replace them with a hash-based name
-        for (var i = 0; i < members.Count; i++)
-        {
-            if (contested[i])
-            {
-                result[i] = $"{result[i] ?? $"{prefix}_Type"}_{GeneratedSourceOutput.CreateStableHash($"{members[i].TypeName}|{members[i].AssemblyName}")}";
-            }
+            var member = members[i];
+            var key = TryGetTypeKey(member.Type) ?? "Type";
+            var identity = $"{member.TypeName.Length}:{member.TypeName}{member.AssemblyName.Length}:{member.AssemblyName}";
+            var hash = $"{GeneratedSourceOutput.CreateStableHash(identity)}{GeneratedSourceOutput.CreateStableHash(identity, SecondaryHashSeed)}";
+            result[i] = $"{prefix}_{key}_{hash}";
         }
 
         return result;

src/Orleans.CodeGenerator/build/Microsoft.Orleans.CodeGenerator.props

@@ -6,14 +6,13 @@
     <CompilerVisibleProperty Include="Orleans_GenerateFieldIds" />
     <CompilerVisibleProperty Include="Orleans_ConstructorAttributes" />
     <CompilerVisibleProperty Include="OrleansGenerateCompatibilityInvokers" />
-    <CompilerVisibleProperty Include="Orleans_HotReload" />
+    <CompilerVisibleProperty Include="OrleansHotReload" />
   </ItemGroup>
 
   <PropertyGroup>
     <Orleans_DesignTimeBuild>$(DesignTimeBuild)</Orleans_DesignTimeBuild>
     <Orleans_GenerateFieldIds>$(OrleansGenerateFieldIds)</Orleans_GenerateFieldIds>
     <Orleans_ConstructorAttributes>$(OrleansConstructorAttributes)</Orleans_ConstructorAttributes>
-    <Orleans_HotReload>$(OrleansHotReload)</Orleans_HotReload>
   </PropertyGroup>
 
 </Project>

test/Orleans.CodeGenerator.Tests/GeneratedFieldNamesTests.cs

@@ -34,7 +34,14 @@ public async Task TypeKeyedNamesAreReadableForCommonShapes()
             new FakeMember(compilation.GetTypeByMetadataName("System.Collections.Generic.Dictionary`2")!.Construct(compilation.GetSpecialType(SpecialType.System_String), intType), 3),
         };
 
-        Assert.Equal(["_codec_Int32", "_codec_List_Int32", "_codec_Int32_1", "_codec_Dictionary_String_Int32"], GeneratedFieldNames.ForTypes("_codec", members));
+        var names = GeneratedFieldNames.ForTypes("_codec", members);
+        Assert.Collection(
+            names,
+            name => Assert.Matches("^_codec_Int32_[0-9A-F]{16}$", name),
+            name => Assert.Matches("^_codec_List_Int32_[0-9A-F]{16}$", name),
+            name => Assert.Matches("^_codec_Int32_1_[0-9A-F]{16}$", name),
+            name => Assert.Matches("^_codec_Dictionary_String_Int32_[0-9A-F]{16}$", name));
+        Assert.Equal(names.Length, names.Distinct(StringComparer.Ordinal).Count());
     }
 
     [Fact]
@@ -50,12 +57,29 @@ namespace Second { public class Item { } }
         var names = GeneratedFieldNames.ForTypes("_copier", [first, second]);
         var reversed = GeneratedFieldNames.ForTypes("_copier", [second, first]);
 
-        Assert.All(names, name => Assert.Matches("^_copier_Item_[0-9A-F]{8}$", name));
+        Assert.All(names, name => Assert.Matches("^_copier_Item_[0-9A-F]{16}$", name));
         Assert.NotEqual(names[0], names[1]);
         Assert.Equal(names[0], reversed[1]);
         Assert.Equal(names[1], reversed[0]);
     }
 
+    [Fact]
+    public async Task AddingCollidingSimpleNameDoesNotRenameExistingField()
+    {
+        var compilation = await Compile("""
+            namespace First { public class Item { } }
+            namespace Second { public class Item { } }
+            """);
+        var first = new FakeMember(compilation.GetTypeByMetadataName("First.Item")!, 0);
+        var second = new FakeMember(compilation.GetTypeByMetadataName("Second.Item")!, 1);
+
+        var originalName = Assert.Single(GeneratedFieldNames.ForTypes("_copier", [first]));
+        var namesWithCollision = GeneratedFieldNames.ForTypes("_copier", [first, second]);
+
+        Assert.Equal(originalName, namesWithCollision[0]);
+        Assert.NotEqual(namesWithCollision[0], namesWithCollision[1]);
+    }
+
     [Fact]
     public async Task UnspeakableTypesFallBackToHashOnlyNames()
     {
@@ -64,7 +88,7 @@ public async Task UnspeakableTypesFallBackToHashOnlyNames()
         var members = new List<IMemberDescription> { new FakeMember(pointer, 0) };
 
         var name = Assert.Single(GeneratedFieldNames.ForTypes("_codec", members));
-        Assert.Matches("^_codec_Type_[0-9A-F]{8}$", name);
+        Assert.Matches("^_codec_Type_[0-9A-F]{16}$", name);
 
         Assert.Equal(name, Assert.Single(GeneratedFieldNames.ForTypes("_codec", members)));
     }