Skip to content

Commit 34d04c4

Browse files
Copilotarturcic
Copilot
and
arturcic
committed
Add AOT compatibility documentation and tests
Co-authored-by: arturcic <[email protected]>
1 parent 88e470d commit 34d04c4

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

‎docs/input/docs/reference/aot-compatibility.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# YamlDotNet AOT Compatibility Status
2+
3+
## Summary
4+
5+
This document describes the AOT (Ahead-of-Time) compilation compatibility status of YamlDotNet in the GitVersion project and the infrastructure that has been put in place to support future AOT scenarios.
6+
7+
## Current Status
8+
9+
✅ **Infrastructure Added**: The necessary infrastructure for AOT compatibility has been added to the project.
10+
⚠️ **Source Generator Issues**: The YamlDotNet source generator currently has known bugs that prevent full AOT functionality.
11+
📋 **Ready for Future**: Once the source generator issues are resolved, minimal changes will be needed to enable full AOT support.
12+
13+
## What Has Been Implemented
14+
15+
### 1. YamlDotNet.Analyzers.StaticGenerator Package
16+
17+
The `Vecc.YamlDotNet.Analyzers.StaticGenerator` package (version 16.3.0) has been added to the project. This package provides a source generator that is designed to create AOT-compatible serialization code at compile time, eliminating the need for runtime reflection.
18+
19+
**Package Reference:**
20+
```xml
21+
<PackageReference Include="Vecc.YamlDotNet.Analyzers.StaticGenerator" Version="16.3.0">
22+
<PrivateAssets>all</PrivateAssets>
23+
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
24+
</PackageReference>
25+
```
26+
27+
### 2. YamlConfigurationContext Class
28+
29+
A static context class has been created in the `GitVersion.Configuration` namespace. This class declares all configuration types that need to be serialized/deserialized:
30+
31+
```csharp
32+
[YamlStaticContext]
33+
[YamlSerializable(typeof(GitVersionConfiguration))]
34+
[YamlSerializable(typeof(BranchConfiguration))]
35+
[YamlSerializable(typeof(IgnoreConfiguration))]
36+
[YamlSerializable(typeof(PreventIncrementConfiguration))]
37+
[YamlSerializable(typeof(Dictionary<string, string>))]
38+
[YamlSerializable(typeof(Dictionary<string, BranchConfiguration>))]
39+
[YamlSerializable(typeof(HashSet<string>))]
40+
public partial class YamlConfigurationContext : StaticContext
41+
{
42+
}
43+
```
44+
45+
The source generator is designed to create the implementation of this partial class at compile time.
46+
47+
### 3. Tests
48+
49+
Basic tests have been added to verify the infrastructure is in place (`YamlAotCompatibilityTests`).
50+
51+
## Known Issues
52+
53+
### Source Generator Warnings
54+
55+
When building the project, you may see warnings like:
56+
57+
```
58+
warning CS8785: Generator 'TypeFactoryGenerator' failed to generate source.
59+
It will not contribute to the output and compilation errors may occur as a result.
60+
Exception was of type 'IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'.
61+
```
62+
63+
**Impact**: The source generator fails to generate the necessary code, so `StaticSerializerBuilder` and `StaticDeserializerBuilder` cannot be used yet.
64+
65+
**Cause**: This is a known issue with the `Vecc.YamlDotNet.Analyzers.StaticGenerator` package when processing certain types, particularly:
66+
- Record types
67+
- Complex nested types
68+
- Types with certain patterns
69+
70+
**Tracking**: See https://github.com/aaubry/YamlDotNet/issues/740 and related issues.
71+
72+
## Current Implementation
73+
74+
The `ConfigurationSerializer` class continues to use the reflection-based `SerializerBuilder` and `DeserializerBuilder` for compatibility:
75+
76+
```csharp
77+
private static IDeserializer Deserializer => new DeserializerBuilder()
78+
.WithNamingConvention(HyphenatedNamingConvention.Instance)
79+
.WithTypeConverter(VersionStrategiesConverter.Instance)
80+
.WithTypeInspector(inspector => new JsonPropertyNameInspector(inspector))
81+
.Build();
82+
```
83+
84+
This works correctly but relies on reflection, which is not compatible with Native AOT.
85+
86+
## Future Migration Path
87+
88+
When the source generator issues are resolved, the migration to AOT-compatible serialization will involve:
89+
90+
### 1. Update ConfigurationSerializer
91+
92+
Replace the reflection-based builders with static builders:
93+
94+
```csharp
95+
private static YamlConfigurationContext Context => new();
96+
97+
private static IDeserializer Deserializer => new StaticDeserializerBuilder(Context)
98+
.WithNamingConvention(HyphenatedNamingConvention.Instance)
99+
.WithTypeConverter(VersionStrategiesConverter.Instance)
100+
.WithTypeInspector(inspector => new JsonPropertyNameInspector(inspector))
101+
.Build();
102+
103+
private static ISerializer Serializer => new StaticSerializerBuilder(Context)
104+
.ConfigureDefaultValuesHandling(DefaultValuesHandling.OmitNull)
105+
.WithTypeInspector(inspector => new JsonPropertyNameInspector(inspector))
106+
.WithNamingConvention(HyphenatedNamingConvention.Instance)
107+
.Build();
108+
```
109+
110+
### 2. Enable AOT in CLI Project
111+
112+
Add AOT publishing configuration to `GitVersion.Cli.csproj`:
113+
114+
```xml
115+
<PropertyGroup>
116+
<PublishAot>true</PublishAot>
117+
<IsAotCompatible>true</IsAotCompatible>
118+
</PropertyGroup>
119+
```
120+
121+
### 3. Address Custom Type Converters
122+
123+
Custom type converters like `VersionStrategiesConverter` may need to be reviewed for AOT compatibility. If they use reflection internally, they will need to be updated.
124+
125+
## Alternative Approaches
126+
127+
If the source generator continues to have issues, alternative approaches include:
128+
129+
1. **Manual StaticContext Implementation**: Implement the required methods of `StaticContext` manually without relying on the source generator.
130+
131+
2. **Hybrid Approach**: Use static serialization for simple types and keep reflection-based serialization for complex custom types, with conditional compilation based on AOT mode.
132+
133+
3. **Alternative Serializers**: Consider alternative YAML libraries that have better AOT support, though this would be a significant change.
134+
135+
## Recommendations
136+
137+
1. **Monitor YamlDotNet Updates**: Keep an eye on YamlDotNet releases for source generator improvements.
138+
139+
2. **Test AOT Compatibility**: Once source generator issues are resolved, test the entire application with `PublishAot` to identify any remaining reflection dependencies.
140+
141+
3. **Incremental Migration**: Start with simple configuration types to verify the source generator works before migrating the entire configuration system.
142+
143+
## Compatibility Matrix
144+
145+
| Component | AOT Ready | Notes |
146+
|-----------|-----------|-------|
147+
| YamlDotNet 16.3.0 | ⚠️ Partial | Core library supports AOT, but source generator has issues |
148+
| YamlConfigurationContext | ✅ Yes | Infrastructure in place |
149+
| ConfigurationSerializer | ❌ No | Still uses reflection-based builders |
150+
| VersionStrategiesConverter | ❌ No | Uses reflection in nested serializers |
151+
| CLI Project | ❌ No | No AOT publishing configuration yet |
152+
153+
## References
154+
155+
- [Andrew Lock: Using the YamlDotNet source generator for Native AOT](https://andrewlock.net/using-the-yamldotnet-source-generator-for-native-aot/)
156+
- [YamlDotNet GitHub Issue #740: Support for Native AOT](https://github.com/aaubry/YamlDotNet/issues/740)
157+
- [YamlDotNet GitHub Repository](https://github.com/aaubry/YamlDotNet)
158+
- [Vecc.YamlDotNet.Analyzers.StaticGenerator NuGet Package](https://www.nuget.org/packages/Vecc.YamlDotNet.Analyzers.StaticGenerator)
159+
- [Microsoft: Prepare .NET libraries for trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/prepare-libraries-for-trimming)
160+
161+
## Conclusion
162+
163+
The infrastructure for YamlDotNet AOT compatibility has been successfully added to the GitVersion project. While the source generator currently has known issues that prevent immediate use, the groundwork is in place for a smooth transition once these issues are resolved. The project is positioned to take advantage of AOT compilation benefits as soon as the YamlDotNet ecosystem matures.

‎src/GitVersion.Configuration.Tests/YamlAotCompatibilityTests.cs‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
using GitVersion.Configuration;
2+
using GitVersion.VersionCalculation;
3+
4+
namespace GitVersion.Core.Tests;
5+
6+
[TestFixture]
7+
public class YamlAotCompatibilityTests
8+
{
9+
[Test]
10+
public void YamlConfigurationContextCanBeInstantiated()
11+
{
12+
// Arrange & Act
13+
var context = new YamlConfigurationContext();
14+
15+
// Assert
16+
// The fact that we can instantiate the context means the infrastructure is in place
17+
// Once the source generator issues are resolved, this context will provide AOT-compatible serialization
18+
context.ShouldNotBeNull();
19+
context.ShouldBeOfType<YamlConfigurationContext>();
20+
}
21+
22+
[Test]
23+
public void YamlConfigurationContextHasCorrectBaseType()
24+
{
25+
// Arrange
26+
var context = new YamlConfigurationContext();
27+
28+
// Assert
29+
// Verify it inherits from StaticContext as required by YamlDotNet source generator
30+
context.ShouldBeAssignableTo<YamlDotNet.Serialization.StaticContext>();
31+
}
32+
33+
/// <summary>
34+
/// Note: Full AOT serialization/deserialization tests are currently disabled due to known issues
35+
/// in the Vecc.YamlDotNet.Analyzers.StaticGenerator package (TypeFactoryGenerator failures).
36+
///
37+
/// When the source generator issues are resolved, the following functionality should work:
38+
/// - StaticSerializerBuilder(context).Build() for AOT-compatible serialization
39+
/// - StaticDeserializerBuilder(context).Build() for AOT-compatible deserialization
40+
///
41+
/// See: https://github.com/aaubry/YamlDotNet/issues/740
42+
/// </summary>
43+
[Test]
44+
[Ignore("Source generator has known issues - TypeFactoryGenerator fails with IndexOutOfRangeException")]
45+
public void StaticContextCanSerializeConfiguration()
46+
{
47+
// This test is placeholder for future when source generator is fixed
48+
var context = new YamlConfigurationContext();
49+
// var serializer = new StaticSerializerBuilder(context).Build();
50+
// Test serialization...
51+
}
52+
}

0 commit comments

Comments
 (0)