Guide for working with Thinktecture.Runtime.Extensions - .NET library for Smart Enums, Value Objects, and Discriminated Unions using Roslyn Source Generators
You are working with **Thinktecture.Runtime.Extensions**, a .NET library that provides Smart Enums, Value Objects, and Discriminated Unions through Roslyn Source Generators.
1. **SmartEnumSourceGenerator**: `[SmartEnum<T>]` or `[SmartEnum]` - factory methods, operators, Switch/Map
2. **ValueObjectSourceGenerator**: `[ValueObject<T>]` or `[ComplexValueObject]` - factory methods, equality, operators
3. **AdHocUnionSourceGenerator**: `[Union<T1, T2, ...>]` or `[AdHocUnion(...)]` - conversion operators, Switch/Map
4. **RegularUnionSourceGenerator**: `[Union]` inheritance-based unions - factory methods, Switch/Map
5. **ObjectFactorySourceGenerator**: `[ObjectFactory<T>]` - custom serialization/parsing logic
6. **AnnotationsSourceGenerator**: JetBrains annotations if not already present
1. **ThinktectureRuntimeExtensionsAnalyzer**: 40+ diagnostic rules validating correct usage
2. **ThinktectureRuntimeExtensionsInternalUsageAnalyzer**: Prevents usage of internal library APIs
**Keyless `[SmartEnum]`**: Type-safe enums without underlying values (items as public static readonly fields)
**Keyed `[SmartEnum<TKey>]`**: Type-safe enums with underlying key values (int, string, Guid, custom types)
**Simple `[ValueObject<TKey>]`**: Single-value immutable types (e.g., Amount, ProductId)
**Complex `[ComplexValueObject]`**: Multi-property immutable types (e.g., DateRange)
**Ad-hoc `[Union<T1, T2>]`**: Simple 2-5 type combinations with implicit conversion operators
**Regular `[Union]`**: Inheritance-based unions with derived types and static factory methods
**NEVER guess or assume API behavior for external libraries/frameworks:**
1. **Use Context7 MCP** to verify external APIs:
- `mcp__context7__resolve-library-id` to find library ID
- `mcp__context7__get-library-docs` to retrieve accurate documentation
- Required for: .NET BCL, ASP.NET Core, Entity Framework Core, serialization frameworks, Roslyn APIs
2. **State uncertainty explicitly**: "I need to verify the API behavior using Context7"
3. **This project's code is authoritative** - use Serena tools to explore internal codebase
**ALWAYS delegate to subagents for:**
**Do NOT delegate:**
**Always prefer `ValidateFactoryArguments` over `ValidateConstructorArguments`:**
1. **Types must be `partial`** for source generators to work
2. **String-based keys/members**: Always explicitly specify equality comparer (`[KeyMemberEqualityComparer<MyType, string, StringComparer>]`)
3. **Immutability**: All members readonly (fields) or no setter/private init (properties)
4. **Constructors**: Keep private to enforce factory method usage
5. **Smart Enum items**: Must be public static readonly fields
6. **Arithmetic operators**: Use unchecked arithmetic context (overflow wraps around)
Generated types implement `IMetadataOwner` interface enabling:
The `MetadataLookup` class provides cached metadata discovery via reflection. Object factories have priority over key-based metadata.
**Essential reading**: See "Runtime Metadata System" section in `CLAUDE-FEATURE-DEV.md` when implementing serialization integrations or custom conversion logic.
```bash
dotnet build
dotnet restore
dotnet test
```
**Serialization**: System.Text.Json, MessagePack, Newtonsoft.Json, ProtoBuf - reference package for auto-generation or manually register converters
**Entity Framework Core**: Version-specific packages (8/9/10) - call `.UseThinktectureValueConverters()` on DbContextOptionsBuilder
**ASP.NET Core**: Model binding via `IParsable<T>` interface (auto-generated) - use `[ObjectFactory<string>]` for custom parsing
**Swashbuckle/OpenAPI**: Schema and operation filters for proper documentation
| Issue | Solution |
|-------|----------|
| "Type must be partial" | Add `partial` keyword to class/struct |
| "String-based value object needs equality comparer" | Add `[KeyMemberEqualityComparer<MyType, string, StringComparer>]` |
| "Smart enum has no items" | Ensure items are public static readonly fields |
| Serialization not working | Reference integration package or manually register converters |
| EF Core not converting | Call `.UseThinktectureValueConverters()` on DbContextOptionsBuilder |
| ISpanParsable not available | Requires NET9+ target framework and key type implementing `ISpanParsable<TKey>` |
Consult these files in the repository for specific tasks:
When adding a new feature:
1. User requests feature → Use `feature-implementation-planner` subagent to create plan
2. Plan approved → Use `feature-implementer` subagent to write code
3. Implementation complete → Use `feature-test-writer` subagent to add tests
4. Tests passing → Use `documentation-updater` subagent to update docs
5. All done → Use `feature-reviewer` subagent for final review
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/thinktectureruntimeextensions-guide/raw