Add backward compatibility for object-typed AdditionalProperties

[Copilot]

✅ Implementation Complete: Add backward compatibility support for object-typed AdditionalProperties

Issue Resolved

Successfully implemented backward compatibility for models with IDictionary<string, object> AdditionalProperties (from old generator) that are now generated as IDictionary<string, BinaryData> (in new generator).

Final Solution

Core Approach: Matching Backing Field Types

The solution detects when a model previously had object-typed AdditionalProperties and creates the backing field with the appropriate type, ensuring perfect type alignment between field and property.

Files Changed

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/ModelProvider.cs

• Added object dictionary type support alongside BinaryData
• Added early backward compatibility detection via ShouldUseObjectAdditionalProperties()
• Updated BuildRawDataField() to create field with object or BinaryData type based on backward compat needs
• Updated property generation logic to use matching backing field type
• Added comprehensive XML documentation
• Fixed null-safety issues with IsFrameworkType checks

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/ModelProviders/ModelProviderTests.cs

• Added TestBuildProperties_WithObjectAdditionalPropertiesBackwardCompatibility test

packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/MrwSerializationTypeDefinitions/AdditionalPropertiesTest.cs

• Added comprehensive deserialization test verifying all code aspects
• Added comprehensive serialization test verifying all code aspects
• Both tests validate complete generated code with detailed assertions

packages/http-client-csharp/generator/docs/backward-compatibility.md

• Added new section "AdditionalProperties Type Preservation"
• Documents the object-to-BinaryData migration scenario
• Provides examples of before/after code
• Explains serialization/deserialization behavior differences
• Formatted with prettier (removed trailing whitespace)

Test Results ✅

• 1232/1232 Microsoft.TypeSpec.Generator.Tests PASSED
• 1014/1014 Microsoft.TypeSpec.Generator.ClientModel.Tests PASSED
• 10/10 AdditionalPropertiesTest tests PASSED
• 2/2 Serialization backward compatibility tests with comprehensive assertions PASSED

Comprehensive Test Coverage

Deserialization test verifies:

• Variable declaration: IDictionary<string, object> additionalProperties
• Dictionary initialization: ChangeTrackingDictionary<string, object>()
• Property enumeration: foreach (var prop in element.EnumerateObject())
• Property name checks: prop.NameEquals("name"u8)
• Type-specific methods: GetString() for known properties, GetObject() for additional properties
• Constructor call with proper parameters

Serialization test verifies:

• Format validation and error handling
• Property name serialization: writer.WritePropertyName("name"u8)
• Property value serialization: writer.WriteStringValue(Name)
• Foreach iteration over AdditionalProperties
• Key serialization: writer.WritePropertyName(item.Key)
• Value serialization: writer.WriteObjectValue<object>(item.Value, options)
• Options.Format handling

Backward Compatibility Guarantees

Scenario	Result
Existing library with object type	✅ Maintains object type when regenerated
New library without previous version	✅ Uses BinaryData type (new default)
Binary compatibility	✅ Fully maintained - same types
Source compatibility	✅ Fully maintained - code compiles
Serialization	✅ Works with both types - fully verified
Deserialization	✅ Works with both types - fully verified

Ready for Merge

This PR successfully resolves the issue with comprehensive test coverage and documentation updates.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add backcompat support for public AdditionalProperties property on models defined as object valued dictionary</issue_title>
<issue_description>In the old generator, we would generate AdditionalProperties as IDictionary<string, object>. In the new generator, we use IDictionary<string, BinaryData>. We will need to implement support for object for backwards compatibility.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add backcompat support for public AdditionalProperties property on models defined as object valued dictionary #9515

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[JoshLove-msft]

@copilot we need to update https://github.com/microsoft/typespec/blob/main/packages/http-client-csharp/generator/docs/backward-compatibility.md

[Copilot]

@copilot we need to update https://github.com/microsoft/typespec/blob/main/packages/http-client-csharp/generator/docs/backward-compatibility.md

Updated backward-compatibility.md in commit a6fcfe2.

Added new section "AdditionalProperties Type Preservation" that documents:

• The object-to-BinaryData migration scenario
• Before/after code examples showing type preservation
• Key points about serialization/deserialization behavior
• When and why this backward compatibility is applied

The section is added to the table of contents and placed after "Model Properties" section.

[JoshLove-msft]

@copilot run format with write for the docs changes

[Copilot]

@copilot run format with write for the docs changes

Formatted backward-compatibility.md with prettier in commit 87f04ec. Removed trailing whitespace from blank lines in code blocks.