You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+15-9Lines changed: 15 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,6 +38,7 @@ The repository is organized as follows:
38
38
-`Thinktecture.Runtime.Extensions.EntityFrameworkCore7`: Provides integration with Entity Framework Core 7.
39
39
-`Thinktecture.Runtime.Extensions.EntityFrameworkCore8`: Provides integration with Entity Framework Core 8.
40
40
-`Thinktecture.Runtime.Extensions.EntityFrameworkCore9`: Provides integration with Entity Framework Core 9.
41
+
-`Thinktecture.Runtime.Extensions.EntityFrameworkCore10`: Provides integration with Entity Framework Core 10.
41
42
-`Thinktecture.Runtime.Extensions.AspNetCore`: Provides extensions for ASP.NET Core, primarily for model binding of Smart Enums, Value Objects, and Discriminated Unions.
42
43
-`Thinktecture.Runtime.Extensions.Swashbuckle`: Provides extensions for Swashbuckle (OpenAPI).
43
44
-**`test/`**: Contains unit tests, with a structure that mirrors the `src/` directory.
@@ -62,16 +63,19 @@ The repository is organized as follows:
62
63
## Core Feature Details
63
64
64
65
### Value Objects (`[ValueObject]`, `[ComplexValueObject]`)
66
+
65
67
-**Simple vs. Complex**: The library distinguishes between simple (keyed) value objects that wrap a single value, and complex value objects that compose multiple properties.
66
68
-**Validation**: Prefer implementing the static partial method `ValidateFactoryArguments` for validation logic. This allows for returning a `ValidationError` and is used by factory methods (`Create`, `TryCreate`, `Validate`). Avoid `ValidateConstructorArguments` as it can only throw exceptions, which integrates poorly with frameworks.
67
69
-**Customization**: Pay attention to attributes like `[KeyMemberEqualityComparer]` for custom equality logic (especially for strings) and `[ObjectFactory]` for custom serialization/parsing behavior.
68
70
69
71
### Smart Enums (`[SmartEnum]`)
72
+
70
73
-**Keyed vs. Keyless**: Smart Enums can have a key (e.g., `[SmartEnum<string>]`) or be keyless (`[SmartEnum]`).
71
74
-**Rich Behavior**: They are not just constants; they can have properties, methods, and item-specific behavior (often implemented via inheritance or delegates using `[UseDelegateFromConstructor]`).
72
75
-**Pattern Matching**: Use the generated `Switch` and `Map` methods for exhaustive, type-safe pattern matching.
73
76
74
77
### Discriminated Unions (`[Union]`)
78
+
75
79
-**Ad-hoc vs. Regular**: The library supports simple, ad-hoc unions (`[Union<T1, T2>]`) for combining a few types, and regular, inheritance-based unions for modeling more complex domain hierarchies.
76
80
-**Serialization**: Ad-hoc unions do not serialize to polymorphic JSON by default. For custom serialization (e.g., to a string), use the `[ObjectFactory<T>]` attribute. Regular unions can be persisted in EF Core using TPH and serialized to polymorphic JSON using `[JsonDerivedType]`.
77
81
-**Pattern Matching**: Like Smart Enums, use the generated `Switch` and `Map` methods for exhaustive matching.
@@ -116,9 +120,10 @@ When making changes, please ensure that:
116
120
- You preview your changes to ensure they render correctly before submitting a pull request.
117
121
118
122
## Framework Integration Notes
123
+
119
124
-**JSON/MessagePack Serialization**: There are two ways to enable serialization for the library types:
120
-
1.**Project Reference**: Add a reference to the corresponding integration package (e.g., `Thinktecture.Runtime.Extensions.Json`) in the project where the type is defined. This automatically adds the necessary converter attributes. This is the preferred approach.
121
-
2.**Manual Registration**: Register the converter factory (e.g., `ThinktectureJsonConverterFactory`) in your application's `Startup.cs` or `Program.cs`.
125
+
1.**Project Reference**: Add a reference to the corresponding integration package (e.g., `Thinktecture.Runtime.Extensions.Json`) in the project where the type is defined. This automatically adds the necessary converter attributes. This is the preferred approach.
126
+
2.**Manual Registration**: Register the converter factory (e.g., `ThinktectureJsonConverterFactory`) in your application's `Startup.cs` or `Program.cs`.
122
127
-**Entity Framework Core**: Use the `.UseThinktectureValueConverters()` extension method on `DbContextOptionsBuilder` to automatically configure value converters for all supported types in your model. For regular Discriminated Unions, you may need to configure the discriminator manually.
123
128
-**ASP.NET Core Model Binding**: For types to be bindable from the request path, query, or body, they often rely on the `IParsable<T>` interface, which the source generator implements. For string-based keys or custom parsing logic, the `[ObjectFactory<string>]` attribute is essential.
124
129
@@ -128,17 +133,18 @@ When making changes, please ensure that:
128
133
129
134
When adding support for a new library (e.g., a new serializer, ORM, or web framework), follow these steps:
130
135
131
-
1.**Create a new source project**: Add a new `.csproj` file under the `src/` directory (e.g., `src/Thinktecture.Runtime.Extensions.NewIntegration`).
132
-
2.**Create a new test project**: Add a corresponding test project under the `test/` directory (e.g., `test/Thinktecture.Runtime.Extensions.NewIntegration.Tests`).
133
-
3.**Add projects to the solution**: Use `dotnet sln add` to include both the new source and test projects in the main solution file.
134
-
4.**Add dependencies**:
136
+
1.**Create a new source project**: Add a new `.csproj` file under the `src/` directory (e.g., `src/Thinktecture.Runtime.Extensions.NewIntegration`).
137
+
2.**Create a new test project**: Add a corresponding test project under the `test/` directory (e.g., `test/Thinktecture.Runtime.Extensions.NewIntegration.Tests`).
138
+
3.**Add projects to the solution**: Use `dotnet sln add` to include both the new source and test projects in the main solution file.
139
+
4.**Add dependencies**:
135
140
- The new source project should reference the core `Thinktecture.Runtime.Extensions` project.
136
141
- Add a package reference for the library you are integrating with. Manage the version in the `Directory.Packages.props` file.
137
-
5.**Implement the integration logic**: Write the necessary code, such as custom converters, providers, or extension methods.
138
-
6.**Write comprehensive tests**: Add unit tests in the test project to ensure the integration works correctly and handles edge cases.
139
-
7.**Update the documentation**: Modify the existing documentation for Value Objects (`Value-Objects.md`), Smart Enums (`Smart-Enums.md`), and/or Discriminated Unions (`Discriminated-Unions.md`) in the `docs/` directory to include information about the new integration. Avoid creating a new documentation file for the integration itself.
142
+
5.**Implement the integration logic**: Write the necessary code, such as custom converters, providers, or extension methods.
143
+
6.**Write comprehensive tests**: Add unit tests in the test project to ensure the integration works correctly and handles edge cases.
144
+
7.**Update the documentation**: Modify the existing documentation for Value Objects (`Value-Objects.md`), Smart Enums (`Smart-Enums.md`), and/or Discriminated Unions (`Discriminated-Unions.md`) in the `docs/` directory to include information about the new integration. Avoid creating a new documentation file for the integration itself.
140
145
141
146
### Common Use Cases
147
+
142
148
When implementing new features, consider these common patterns from the documentation:
@@ -27,18 +28,21 @@ This library provides some interfaces, classes, [Roslyn Source Generators](https
27
28
See [wiki](https://github.com/PawelGerr/Thinktecture.Runtime.Extensions/wiki) for more documentation.
28
29
29
30
**Value Objects articles**:
31
+
30
32
*[Value Objects: Solving Primitive Obsession in .NET](https://www.thinktecture.com/en/net/value-objects-solving-primitive-obsession-in-net/)
31
33
*[Handling Complexity: Introducing Complex Value Objects in .NET](https://www.thinktecture.com/en/net/handling-complexity-introducing-complex-value-objects-in-dotnet/)
32
34
*[Value Objects in .NET: Integration with Frameworks and Libraries](https://www.thinktecture.com/en/net/value-objects-in-net-integration-with-frameworks-and-libraries/)
33
35
*[Value Objects in .NET: Enhancing Business Semantics](https://www.thinktecture.com/en/net/value-objects-in-dotnet-enhancing-business-semantics/)
34
36
*[Advanced Value Object Patterns in .NET](https://www.thinktecture.com/en/net/advanced-value-object-patterns-in-net/)
35
37
36
38
**Smart Enums articles**:
39
+
37
40
*[Smart Enums: Beyond Traditional Enumerations in .NET](https://www.thinktecture.com/en/net/smart-enums-beyond-traditional-enumerations-in-dotnet/)
38
41
*[Smart Enums: Adding Domain Logic to Enumerations in .NET](https://www.thinktecture.com/en/net/smart-enums-adding-domain-logic-to-enumerations-in-dotnet/)
39
42
*[Smart Enums in .NET: Integration with Frameworks and Libraries](https://www.thinktecture.com/en/net/smart-enums-in-net-integration-with-frameworks-and-libraries/)
40
43
41
44
**Discriminated Unions articles**:
45
+
42
46
*[Discriminated Unions: Representation of Alternative Types in .NET](https://www.thinktecture.com/en/net/discriminated-unions-representation-of-alternative-types-in-dotnet/)
43
47
*[Pattern Matching with Discriminated Unions in .NET](https://www.thinktecture.com/en/net/pattern-matching-with-discriminated-unions-in-net/)
44
48
*[Discriminated Unions in .NET: Modeling States and Variants](https://www.thinktecture.com/en/net/discriminated-unions-in-net-modeling-states-and-variants/)
@@ -85,6 +89,7 @@ Discriminated Unions:
85
89
86
90
Smart Enums provide a powerful alternative to traditional C# enums, offering type-safety, extensibility, and rich behavior.
87
91
Unlike regular C# enums which are limited to numeric values and lack extensibility, Smart Enums can:
92
+
88
93
* Use any type as the underlying type (e.g., strings, integers) or none at all
89
94
* Include additional fields, properties and behavior
90
95
* Use polymorphism to define custom behavior for each value
@@ -110,6 +115,7 @@ Some of the Key Features are:
110
115
Roslyn Analyzers and CodeFixes help the developers to implement the Smart Enums correctly
111
116
112
117
Provides support for:
118
+
113
119
* JSON (System.Text.Json and Newtonsoft)
114
120
* Minimal Api Parameter Binding and ASP.NET Core Model Binding
115
121
* Entity Framework Core
@@ -354,6 +360,7 @@ Value objects help solve several common problems in software development:
354
360
```
355
361
356
362
Key Features:
363
+
357
364
* Two types of value objects:
358
365
* Simple value objects (wrapper around a single value with validation)
359
366
* Complex value objects (multiple properties representing a single concept)
0 commit comments