Thinktecture Runtime Extensions

https://github.com/pawelgerr/thinktecture.runtime.extensions
Admin
A .NET library that uses Roslyn Source Generators, Analyzers, and CodeFixes to give you Smart Enums,...
Tokens:221,904
Snippets:1,314
Trust Score:7.5
License:BSD-3-Clause
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Quick Start: OrderStatus Smart Enum

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Quick start example for creating a string-based Smart Enum. Requires the Thinktecture.Runtime.Extensions NuGet package, a partial class, and the [SmartEnum<TKey>] attribute. Items must be public static readonly fields; the private constructor and other features are generated automatically.

```csharp
[SmartEnum<string>]                       // 1. Apply the SmartEnum attribute with key type
public partial class OrderStatus          // 2. Class must be partial
{
   public static readonly OrderStatus Pending = new("Pending");       // 3. Items are public static readonly
   public static readonly OrderStatus Processing = new("Processing");
   public static readonly OrderStatus Completed = new("Completed");
   public static readonly OrderStatus Cancelled = new("Cancelled");
}
```

--------------------------------

### Install Thinktecture.Runtime.Extensions.Serilog package

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Serilog

Install the Serilog integration package with the dotnet CLI. Requires Serilog 4.0.0 or later.

```bash
dotnet add package Thinktecture.Runtime.Extensions.Serilog
```

--------------------------------

### Amount usage examples

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects

Shows creating Amount instances, equality comparisons, and arithmetic operations with decimal overloads.

```csharp
// get an instance of amount from database, with Create/TryCreate or an explicit cast
var amount = Amount.Create(1m);
var otherAmount = (Amount)2m;
var zero = Amount.Zero;

// equality comparisons
amount == zero; // false
amount > otherAmount; // false
amount > 42m; // false
amount.CompareTo(otherAmount); // -1

// arithmetic operations
amount + otherAmount; // 3
amount + 42m // 43
```

--------------------------------

### Period usage examples

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects

Shows creating Period instances, validation failure throwing ValidationException, equality comparison, and intersection checking.

```csharp
// Creating Period instances
var startDate = new DateOnly(2023, 1, 1);
var endDate = OpenEndDate.Create(2023, 12, 31);
var period = Period.Create(startDate, endDate);

// Validation examples
try
{
   var invalidPeriod = Period.Create(
      new DateOnly(2023, 12, 31),
      OpenEndDate.Create(2023, 1, 1)
   ); // Throws ValidationException
}
catch (ValidationException ex)
{
   Console.WriteLine(ex.Message); // "From must be earlier than Until"
}

// Equality comparison
var samePeriod = Period.Create(startDate, endDate);
var areEqual = period == samePeriod; // True
Console.WriteLine($"period == samePeriod: {areEqual}");

// Checking if period intersects with another period
var otherPeriod = Period.Create(new DateOnly(2023, 6, 1),
                                OpenEndDate.Create(2024, 6, 1));
var intersects = period.IntersectsWith(otherPeriod); // true
Console.WriteLine($"period.IntersectsWith(otherPeriod): {intersects}");
```

--------------------------------

### ISpanParsable<T> zero-allocation parsing with ValueObject

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects-Customization

Shows how keyed value objects automatically implement ISpanParsable<T> when the key type supports it, enabling zero-allocation parsing with ReadOnlySpan<char>. Includes examples for int, decimal, DateTime, and Guid key types.

```csharp
[ValueObject<int>]
public readonly partial struct CustomerId
{
}

// ISpanParsable<T> implementation
// Zero-allocation parsing for high-performance scenarios
ReadOnlySpan<char> span = "12345".AsSpan();
bool success = CustomerId.TryParse(span, null, out CustomerId? id);

// Works with numeric types (int, long, decimal, etc.)
[ValueObject<decimal>]
public readonly partial struct Amount
{
}

ReadOnlySpan<char> amountSpan = "99.99".AsSpan();
Amount? amount = Amount.Parse(amountSpan, null);

// Works with DateTime, Guid, and other ISpanParsable types
[ValueObject<DateTime>]
public readonly partial struct OrderDate
{
}

[ValueObject<Guid>]
public readonly partial struct ProductId
{
}
```

--------------------------------

### Daily sales CSV example

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Example CSV for daily sales with columns id, datetime, volume. The datetime format is 'yyyyMMdd hh:mm'.

```csv
id,datetime,volume
1,20230425 10:45,345.67
```

--------------------------------

### Custom conversion across all formats with [ObjectFactory<T>]

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums-Framework-Integration

Apply [ObjectFactory<T>] with UseForSerialization = SerializationFrameworks.All to override default key-based conversion. The example stores the serialization value as a constructor parameter and implements Validate and ToValue methods.

```csharp
[SmartEnum<int>]
[ObjectFactory<string>(UseForSerialization = SerializationFrameworks.All)]
public partial class ShippingMethod
{
   public static readonly ShippingMethod Standard = new(1, slug: "standard");
   public static readonly ShippingMethod Express = new(2, slug: "express");
   public static readonly ShippingMethod Overnight = new(3, slug: "overnight");

   public string Slug { get; }

   private ShippingMethod(int key, string slug) : this(key)
   {
      Slug = slug;
   }

   public static ValidationError? Validate(
      string? value, IFormatProvider? provider, out ShippingMethod? item)
   {
      item = Items.FirstOrDefault(i => i.Slug.Equals(value, StringComparison.OrdinalIgnoreCase));
      return item is null ? new ValidationError($"Unknown shipping method '{value}'") : null;
   }

   public string ToValue() => Slug;
}
```

--------------------------------

### Create empty read-only collections with Empty.Collection, Empty.Dictionary, Empty.Lookup, and Empty.Set

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Empty-...

Shows how to create empty read-only collections using Empty.Collection(), Empty.Dictionary(), Empty.Lookup(), and Empty.Set(). The example passes them to methods expecting IEnumerable, IEnumerable<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, IReadOnlyDictionary<TKey, TValue>, ILookup<TKey, TValue>, and IReadOnlySet<T>.

```C#
public static void Main()
{
	Method_1(Empty.Collection());
	Method_2(Empty.Collection<string>());
	Method_3(Empty.Collection<int>());
	Method_4(Empty.Collection<int>());

	Method_5(Empty.Dictionary<string, int>());
	Method_6(Empty.Lookup<string, int>());
	Method_7(Empty.Set<string>());
}

public static void Method_1(IEnumerable collection)
{
}

public static void Method_2(IEnumerable<string> collection)
{
}

public static void Method_3(IReadOnlyCollection<int> collection)
{
}

public static void Method_4(IReadOnlyList<int> collection)
{
}

public static void Method_5(IReadOnlyDictionary<string, int> dictionary)
{
}

public static void Method_6(ILookup<string, int> lookup)
{
}

public static void Method_7(IReadOnlySet<string> set)
{
}
```

--------------------------------

### TrimOrNullify()

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/TrimOrNullify

Documentation for the TrimOrNullify extension method, including its behavior and usage example.

```APIDOC
## TrimOrNullify()

### Description
Convenience method for trimming, truncating and nullifying of `string`. If the string is empty or contains only whitespace, it returns `null`; otherwise it returns the trimmed string. If `maxLength` is provided, the string is shortened if necessary.

### Method
Extension method

### Endpoint
`string.TrimOrNullify()`

### Parameters
#### Optional Parameters
- **maxLength** (int) - Optional - Maximum length of the returned string. If provided, the trimmed string is shortened to this length if necessary.

### Return Value
- Returns `null` if the input string is empty or contains only whitespace.
- Otherwise returns the trimmed string, optionally shortened to `maxLength`.

### Example
```csharp
string value = ...;
var trimmedOrNull = value.TrimOrNullify();
var trimmedAndShortenedOrNull = value.TrimOrNullify(maxLength: 10);
```
```

--------------------------------

### Smart Enum with Base Class and Instance Property

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Extends the base class example by adding an instance property Description. The generated constructor signature becomes (string key, string description, int value) — Smart Enum parameters first, then base class parameters.

```csharp
[SmartEnum<string>]
public partial class SmartEnumWithBaseClass : SomeBaseClass
{
   public string Description { get; }

   public static readonly SmartEnumWithBaseClass Item1 = new("item 1", "A description", 42);
}
```

--------------------------------

### Example — trim and lowercase a string member

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions-Customization

Implements NormalizeText to trim and lowercase the string member before it is stored. The parameter is passed by ref so the value can be replaced in place; the method is optional and erased by the compiler if not implemented.

```csharp
[Union<string, int>(T1Name = "Text", T2Name = "Number")]
public partial class TextOrNumber
{
   static partial void NormalizeText(ref string value)
   {
      value = value?.Trim().ToLowerInvariant();
   }
}
```

--------------------------------

### String-based Smart Enum: ProductType

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

String-based Smart Enum example. Use string keys for human-readable identifiers. The class must be partial and items are public static readonly fields.

```csharp
// Use string as the key type - perfect for human-readable identifiers
[SmartEnum<string>]
public partial class ProductType
{
   // Define your enum items as static readonly fields
   // and pass the corresponding string to constructor
   public static readonly ProductType Electronics = new("Electronics");
   public static readonly ProductType Clothing = new("Clothing");
}
```

--------------------------------

### Two-Way Conversion with ObjectFactory and SerializationFrameworks.All

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Object-Factories

Set UseForSerialization to a non-None value or UseWithEntityFramework = true to add IConvertible<T> requiring a ToValue() method. This example sets SerializationFrameworks.All to generate serialization integration code for all supported frameworks.

```csharp
[SmartEnum<int>]
[ObjectFactory<string>(UseForSerialization = SerializationFrameworks.All)]
public partial class SmartEnumWithFactory
{
   public static readonly SmartEnumWithFactory Item1 = new(1);
   public static readonly SmartEnumWithFactory Item2 = new(2);

   public static ValidationError? Validate(string? value, IFormatProvider? provider, out SmartEnumWithFactory? item)
   {
      switch (value)
      {
         case "=1=":
            item = Item1;
            return null;
         case "=2=":
            item = Item2;
            return null;
         default:
            item = null;
            return new ValidationError($"Unknown value '{value}'");
      }
   }

   // Required by IConvertible<string>
   public string ToValue()
   {
      return $"={Key}=";
   }
}
```

--------------------------------

### Configure TypesToRenderAsString flag in Serilog

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Serilog

Shows how to pass the TypesToRenderAsString flag to the Destructure.UsingThinktectureRuntimeExtensions method. Combine flag values with the bitwise OR operator. The example enables string rendering for SmartEnums and ValueObjects.

```csharp
using Thinktecture;

Log.Logger = new LoggerConfiguration()
    .Destructure.UsingThinktectureRuntimeExtensions(
        renderAsString: TypesToRenderAsString.SmartEnums | TypesToRenderAsString.ValueObjects)
    .WriteTo.Console()
    .CreateLogger();
```

--------------------------------

### Keyless Smart Enum: SalesCsvImporterType

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Keyless Smart Enum example. Use when no serialization is needed. Keyless Smart Enums cannot be serialized or used with model binding out of the box; add [ObjectFactory<string>] to enable framework integration.

```csharp
// No key type needed - useful for cases that don't require serialization
[SmartEnum]
public partial class SalesCsvImporterType
{
   // Items don't need any key, just the instance itself
   public static readonly SalesCsvImporterType Daily = new();
   public static readonly SalesCsvImporterType Monthly = new();
}
```

--------------------------------

### Define and use a SmartEnum<string> with generated operations

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows how to define a smart enum with the [SmartEnum<string>] attribute and use its generated members: Items, Get, TryGet, Validate, TryParse, ToString, and comparison operators. The source generator creates a private constructor, so items are defined as static readonly fields. Get throws if the key is not found, while TryGet returns false. Validate returns a ValidationError? for detailed error information. TryParse enables IParsable<T> support for Minimal APIs. ToString with a format string works for numeric keys, and comparison operators are available when the key type implements IComparable<T>.

```csharp
[SmartEnum<string>]
public partial class ProductType
{
    // The source generator creates a private constructor
    public static readonly ProductType Electronics = new("Electronics");
}

// Enumeration over all defined items
IReadOnlyList<ProductType> allTypes = ProductType.Items;

// Value retrieval
ProductType fromGet = ProductType.Get("Electronics");               // Get by key (throws if not found)
ProductType fromCast = (ProductType)"Electronics";                  // Same as above but using a cast
bool found = ProductType.TryGet("Electronics", out var fromTryGet); // Safe retrieval (returns false if not found)

// Validation with detailed error information
ValidationError? error = ProductType.Validate("Electronics", null, out ProductType? validated);

// IParsable<T> (useful for Minimal APIs)
bool parsed = ProductType.TryParse("Electronics", null, out ProductType? parsedType);

// IFormattable (e.g. for numeric keys)
string formatted = Priority.Low.ToString("000", CultureInfo.InvariantCulture);  // "001"

// IComparable (available when the key type implements IComparable<T>)
int comparison = Priority.Medium.CompareTo(Priority.High);
bool isHigher = Priority.High > Priority.Low;  // Comparison operators
```

--------------------------------

### Monthly sales CSV examples (3 or 4 columns)

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Example CSVs for monthly sales. The 3-column format uses 'yyyyMMdd hh:mm' datetime, while the 4-column format uses 'yyyy-MM-dd'.

```csv
volume,datetime,id
123.45,20230426 11:50,2

OR

volume,quantity,id,datetime
123.45,42,2,2023-04-25
```

--------------------------------

### PartiallyKnownDate Usage

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions

Shows how to instantiate different date precisions and use the Switch method to format them for display.

```csharp
// Date with only year known
var historicalEvent = new PartiallyKnownDate.YearOnly(2000);

// Date with year and month known
var approximateBirthdate = new PartiallyKnownDate.YearMonth(1980, 6);

// Fully known date
var preciseDate = new PartiallyKnownDate.Date(2024, 12, 31);

// Implicit conversion from DateOnly to PartiallyKnownDate
PartiallyKnownDate fullDate = new DateOnly(2024, 3, 15);  // Date(2024, 3, 15)

static string FormatDate(PartiallyKnownDate date)
{
   return date.Switch(
      yearOnly: y => y.Year.ToString(),
      yearMonth: ym => $"{ym.Year}-{ym.Month:D2}",
      date: ymd => $"{ymd.Year}-{ymd.Month:D2}-{ymd.Day:D2}"
   );
}

Console.WriteLine($"Historical event: {FormatDate(historicalEvent)}");              // "2000"
Console.WriteLine($"Approximate birthdate: {FormatDate(approximateBirthdate)}");    // "1980-06"
Console.WriteLine($"Precise date: {FormatDate(preciseDate)}");                      // "2024-12-31"
```

--------------------------------

### Switch and Map usage with ProductType enum

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows how to use Switch for side effects (void), Switch with return value, and Map for direct value mapping. All methods are exhaustive by default.

```csharp
ProductType productType = ProductType.Electronics;

// Execute different actions based on the enum value (void return)
productType.Switch(
    electronics: () => Console.WriteLine("Processing electronics order"),
    clothing: () => Console.WriteLine("Processing clothing order")
);

// Transform enum values into different types
string department = productType.Switch(
    electronics: () => "Consumer Technology",
    clothing: () => "Fashion and Apparel"
);

// Direct mapping to values - clean and concise
decimal discount = productType.Map(
    electronics: 0.05m,    // 5% off electronics
    clothing: 0.10m    // 10% off clothing
);
```

--------------------------------

### Get item by key using T.Get

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Use T.Get to retrieve the item for a provided key. The generic method Get<T, TKey> constrains T to ISmartEnum<TKey, T, ValidationError> and TKey to notnull, then calls T.Get(key) and prints the result.

```csharp
// Use T.Get/TryGet/Validate to get the item for provided key.
Get<ProductType, string>("Electronics");

private static void Get<T, TKey>(TKey key)
   where T : ISmartEnum<TKey, T, ValidationError>
   where TKey : notnull
{
   T item = T.Get(key);

   Console.WriteLine($"Key '{key}' => '{item}'");
}
```

--------------------------------

### Simple mode name conflict example

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions-Customization

This example will fail to compile when using Simple mode because two nested unions contain a type with the same name 'NotFound', causing duplicate parameter name 'notFound' in the generated Switch/Map methods. The C# compiler will report a duplicate parameter name error.

```csharp
[Union(NestedUnionParameterNames = NestedUnionParameterNameGeneration.Simple)]
public partial class Response
{
   public abstract partial class ErrorA : Response
   {
      private ErrorA() { }
      public sealed class NotFound : ErrorA;  // Parameter: notFound
   }

   public abstract partial class ErrorB : Response
   {
      private ErrorB() { }
      public sealed class NotFound : ErrorB;  // Parameter: notFound (CONFLICT!)
   }
}
```

--------------------------------

### Basic usage of OpenEndDate

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects

Shows how to create, manipulate, compare, and print OpenEndDate instances. Demonstrates that default(OpenEndDate) equals Infinite and that comparison operators work with DateOnly.

```csharp
// Creating OpenEndDate
var specificDate = OpenEndDate.Create(2023, 12, 31);
var infiniteDate = OpenEndDate.Infinite;
var defaultDate = default(OpenEndDate); // Same as Infinite

// Date manipulation
var endOfMonth = OpenEndDate.Create(2023, 3, 15).MoveToEndOfMonth(); // 2023-03-31

// Compare the dates
var isLater = infiniteDate > specificDate; // true
var isEqual = infiniteDate == defaultDate; // true

// String representation
Console.WriteLine(specificDate); // "2023-12-31"
Console.WriteLine(infiniteDate); // "Infinite"
```

--------------------------------

### Custom Configuration with Max Length Strategies

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums-Framework-Integration

Creates a Configuration with custom max length strategies for Smart Enums and keyed value objects. Uses DefaultSmartEnumMaxLengthStrategy for automatic calculation and a custom delegate for KeyedValueObjects that returns 200 for ProductName types.

```csharp
new Configuration
{
   SmartEnums = new SmartEnumConfiguration
   {
      // Choose a max length strategy
      MaxLengthStrategy = DefaultSmartEnumMaxLengthStrategy.Instance
   },
   KeyedValueObjects = new KeyedValueObjectConfiguration
   {
      MaxLengthStrategy = new CustomKeyedValueObjectMaxLengthStrategy((type, keyType) =>
      {
         if (type == typeof(ProductName))
            return 200;

         return MaxLengthChange.None;
      })
   }
}
```

--------------------------------

### Implement custom string accessor

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums-Customization

Example implementation of an accessor for members of type string using StringComparer.Ordinal.

```csharp
public class StringOrdinal : IEqualityComparerAccessor<string>
{
  public static IEqualityComparer<string> EqualityComparer => StringComparer.Ordinal;
}
```

--------------------------------

### Order class with state transitions using Switch

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions

Shows an Order class that manages state transitions using the Switch method. It includes a Ship method that checks permissions and updates state, and a GetStatusSummary method that returns a string summary based on the current state.

```csharp
public record UserPermissions(bool CanShipOrder);

public class Order
{
   private readonly List<OrderState> _states;

   public int Id { get; }
   public OrderState CurrentState => _states[^1]; // Get the last state in the list

   public Order(int id, string createdBy)
   {
      Id = id;
      _states = [new OrderState.New(createdBy)]; // Initial state
   }

   // Method for state transition
   public bool Ship(string trackingNumber, string carrier, UserPermissions userPermissions)
   {
      // Use Switch to determine the outcome
      return CurrentState.Switch(
         processing: _ =>
         {
            // Check permission
            if (!userPermissions.CanShipOrder)
               return false; // User does not have permission to ship this order

            // Change state
            _states.Add(new OrderState.Shipped(DateTime.UtcNow, trackingNumber, carrier));
            return true;
         },
         @new: static _ => false,       // Order must be processed before shipping
         shipped: static _ => false,    // Order has already been shipped
         cancelled: static _ => false); // Cannot ship a cancelled order
   }

   // Gets summary string
   public string GetStatusSummary()
   {
      return CurrentState.Switch(
         @new: static state => $"Order created by {state.CreatedBy}.",
         processing: static state => $"Order processing since {state.StartedAt}.",
         shipped: static state => $"Order shipped on {state.ShippedAt} via {state.Carrier}.",
         cancelled: static state => $"Order cancelled on {state.CancelledAt}: {state.Reason}"
      );
   }
}
```

--------------------------------

### Method signature requiring IReadOnlyCollection

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/ToReadOnlyCollection

Declares a method that accepts an IReadOnlyCollection<string> parameter. This is the target method used in the subsequent examples.

```C#
// We have to call this method
public void SomeMethod(IReadOnlyCollection<string> userNames)
{
    ...
}
```

--------------------------------

### Define custom equality comparer with KeyMemberEqualityComparerAttribute

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums-Customization

Use the KeyMemberEqualityComparerAttribute to override the default string comparer. This example changes the comparer from OrdinalIgnoreCase to Ordinal.

```C#
[SmartEnum<string>]
[KeyMemberEqualityComparer<ComparerAccessors.StringOrdinal, string>]
public partial class ProductType
{
   public static readonly ProductType Electronics = new("Electronics");
   public static readonly ProductType Clothing = new("Clothing");
}
```

--------------------------------

### Enable partial matching with SwitchPartially and MapPartially

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions-Customization

Shows how to enable partial overloads for Switch and Map methods using SwitchMapMethodsGeneration.DefaultWithPartialOverloads, and demonstrates usage with a default case.

```csharp
[Union<string, int>(
   SwitchMethods = SwitchMapMethodsGeneration.DefaultWithPartialOverloads,
   MapMethods = SwitchMapMethodsGeneration.DefaultWithPartialOverloads)]
public partial class TextOrNumber;

// Use partial coverage with default case
union.SwitchPartially(
   @default: value => Console.WriteLine($"Default: {value}"),
   @string: text => Console.WriteLine($"Text: {text}")
);

var result = union.MapPartially(
   @default: "Default case",
   @string: "Text"
);
```

--------------------------------

### Configure source generator logging with ThinktectureRuntimeExtensions_SourceGenerator_LogFilePath

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Source-Generator-Configuration

Configure source generator logging in the project file. Set the log file path to an existing folder, optionally provide a file name template, and set the log level (default is Information). Set ThinktectureRuntimeExtensions_SourceGenerator_LogFilePathMustBeUnique to false to avoid multiple log files per project.

```xml
<Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
      ...

      <ThinktectureRuntimeExtensions_SourceGenerator_LogFilePath>C:\temp\samples_logs.txt</ThinktectureRuntimeExtensions_SourceGenerator_LogFilePath>
      <ThinktectureRuntimeExtensions_SourceGenerator_LogLevel>information</ThinktectureRuntimeExtensions_SourceGenerator_LogLevel>
      <ThinktectureRuntimeExtensions_SourceGenerator_LogFilePathMustBeUnique>false</ThinktectureRuntimeExtensions_SourceGenerator_LogFilePathMustBeUnique>

   </PropertyGroup>
</Project>
```

--------------------------------

### HTTP response for OpenEndDate round-trip

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects

Shows the response body for GET and POST requests. Both return the date string "2023-04-05".

```text
GET api/enddate/2023-04-05
  and
POST api/enddate with body "2023-04-05"

return "2023-04-05"
```

--------------------------------

### Generated creation and validation methods (Create, TryCreate, Validate)

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects

Demonstrates the generated creation and validation methods: Create throws ValidationException on invalid input, TryCreate returns false, TryCreate with out error provides details, and Validate returns a ValidationError. The comments show expected outcomes for the given inputs.

```csharp
// Using Create (throws ValidationException if invalid)
var name = ProductName.Create("Widget");       // Success
var amount = Amount.Create(100.50m);           // Success

// Using TryCreate (returns false if invalid)
if (ProductName.TryCreate("ab", out var shortName))
{
    // Won't reach here - validation fails (too short)
}

// Using TryCreate with validation error details
if (!ProductName.TryCreate("ab", out var name, out var error))
{
    Console.WriteLine(error.ToString());  // "Product name must be at least 3 characters"
}

// Using Validate (returns ValidationError if invalid)
ValidationError? error = Amount.Validate(-50m, null, out Amount? invalidAmount);

if (error is not null)
{
    Console.WriteLine(error.ToString());  // "Amount cannot be negative"
}
```

--------------------------------

### Normalizing a Value Object inside a validation hook

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/TrimOrNullify

Example of using TrimOrNullify to normalize a string value object member inside a validation hook.

```APIDOC
## Normalizing a Value Object inside a validation hook

### Description
Shows how to use `TrimOrNullify` to normalize a string member inside `ValidateFactoryArguments` of a value object. The trimmed result is assigned back through the `ref` parameter so the normalized value flows to equality, serialization, and persistence.

### Method
Extension method usage in a validation hook

### Endpoint
`value.TrimOrNullify()` inside `ValidateFactoryArguments`

### Parameters
#### Parameters
- **value** (string) - Required - The string to normalize. Passed by `ref` and updated with the trimmed result.
- **validationError** (ValidationError?) - Required - The validation error to set if the trimmed value is null.

### Behavior
- If `TrimOrNullify` returns `null` (empty or whitespace-only input), a validation error is set.
- Otherwise, the trimmed value is assigned back to `value` for storage and comparison.

### Example
```csharp
[ValueObject<string>]
public partial class ProductName
{
    static partial void ValidateFactoryArguments(
        ref ValidationError? validationError,
        ref string value)
    {
        var trimmed = value.TrimOrNullify();

        if (trimmed is null)
        {
            validationError = new ValidationError("Product name cannot be empty.");
            return;
        }

        value = trimmed; // normalized value is what gets stored and compared
    }
}
```
```

--------------------------------

### Apply KeyMemberComparerAttribute with StringOrdinal

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects-Customization

Use KeyMemberComparerAttribute on a simple value object to specify a custom comparer for ordering. The example uses the predefined ComparerAccessors.StringOrdinal accessor for a string member.

```csharp
[ValueObject<string>]
[KeyMemberComparer<ComparerAccessors.StringOrdinal, string>]
public sealed partial class ProductName
{
}
```

--------------------------------

### OrderProcessor Using ShippingMethod

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows how to use the ShippingMethod Smart Enum in an OrderProcessor to calculate shipping cost and delivery date. Uses TimeProvider for current time.

```csharp
public class OrderProcessor(TimeProvider timeProvider)
{
    public OrderSummary ProcessOrder(Order order, ShippingMethod shipping)
    {
        var shippingCost = shipping.CalculatePrice(order.Weight);
        var deliveryDate = timeProvider.GetLocalNow().AddDays(shipping.EstimatedDays);

        return new OrderSummary
        {
            OrderTotal = order.SubTotal + shippingCost,
            EstimatedDelivery = deliveryDate,
            RequiresSignature = shipping.RequiresSignature,
            ShippingCost = shippingCost
        };
    }
}
```

--------------------------------

### Factory methods for stateless members are parameterless

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions-Customization

Shows that factory methods for stateless members (marked with TXIsStateless = true) are parameterless, as demonstrated with EmptyState.

```csharp
[Union<string, EmptyState>(
    T2IsStateless = true,
    FactoryMethodGeneration = FactoryMethodGeneration.Always)]
public partial class TextOrEmpty;

public readonly record struct EmptyState;

// Generated:
// TextOrEmpty.CreateString(string value)
// TextOrEmpty.CreateEmptyState()  — parameterless because EmptyState is stateless
```

--------------------------------

### Switch return type inference error example

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows a Switch call that will not compile because List<int> and int[] are different types, even though both are assignable to IReadOnlyList<int>.

```csharp
// ERROR: The entire Switch call is flagged red
IReadOnlyList<int> ids = productType.Switch(
    electronics: () => new List<int> { 1, 2, 3 },
    clothing: () => new int[] { 4, 5, 6 }
);
```

--------------------------------

### Type Conversion and Equality

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Demonstrates type conversion and equality operations for SmartEnum items, including implicit conversion, equality operators, hash code, ToString, and TypeConverter support.

```APIDOC
## [SmartEnum] Type Conversion and Equality

### Description
Shows how SmartEnum items can be implicitly converted to their key type, compared for equality, and used with TypeConverter.

### Method
N/A (Source Generator)

### Endpoint
N/A

### Parameters
#### Implicit Conversion
- **key** (string) - Returns the key value.

#### Equality
- **Equals** (bool) - Reference equality (items are singletons).
- **==** (bool) - Operator overloading for equality.
- **!=** (bool) - Operator overloading for inequality.

#### GetHashCode
- **GetHashCode** (int) - Delegates to the key using the configured equality comparer.

#### ToString
- **ToString** (string) - Delegates to the key's ToString().

#### TypeConverter
- **ConvertTo** (string?) - Converts the item to a string.
- **ConvertFrom** (ProductType?) - Converts a string to the item.

### Request Example
N/A

### Response
#### Success Response (N/A)
- **key** (string) - The key value.
- **areEqual** (bool) - True if items are equal.
- **hashCode** (int) - The hash code.
- **name** (string) - The string representation.
- **keyStr** (string?) - The converted string.
- **converted** (ProductType?) - The converted item.

#### Response Example
N/A
```

--------------------------------

### Apply KeyMemberComparerAttribute with StringOrdinal accessor

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums-Customization

Use [KeyMemberComparer<ComparerAccessors.StringOrdinal, string>] on a SmartEnum to specify a custom comparer for key members. The example shows a ProductType enum with Electronics and Clothing members.

```C#
[SmartEnum<string>]
[KeyMemberComparer<ComparerAccessors.StringOrdinal, string>]
public partial class ProductType
{
   public static readonly ProductType Electronics = new("Electronics");
   public static readonly ProductType Clothing = new("Clothing");
}
```

--------------------------------

### Force factory method generation with FactoryMethodGeneration.Always

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions-Customization

Shows how to generate factory methods for all members unconditionally using FactoryMethodGeneration.Always, while implicit conversions are still generated.

```csharp
[Union<string, int>(FactoryMethodGeneration = FactoryMethodGeneration.Always)]
public partial class TextOrNumber;

// Generated factory methods:
// TextOrNumber.CreateString(string value)
// TextOrNumber.CreateInt32(int value)

// Implicit conversions are still generated as usual
TextOrNumber fromString = "hello";                          // implicit conversion
TextOrNumber alsoFromString = TextOrNumber.CreateString("hello"); // factory method
```

--------------------------------

### Return empty IDisposable and IAsyncDisposable with Empty.Disposable and Empty.AsyncDisposable

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Empty-...

Shows how to return empty IDisposable and IAsyncDisposable instances using Empty.Disposable() and Empty.AsyncDisposable(). These provide empty Dispose/DisposeAsync methods.

```C#
public IDisposable Method_1()
{
    return Empty.Disposable();
}

public static IAsyncDisposable Method_2()
{
   return Empty.AsyncDisposable();
}
```

--------------------------------

### Integer-based Smart Enum: Priority

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Integer-based Smart Enum example. Use int keys for persistence or natural ordering. The class must be partial and items are public static readonly fields.

```csharp
// Use int as the key type - useful for persistence or natural ordering
[SmartEnum<int>]
public partial class Priority
{
   public static readonly Priority Low = new(1);
   public static readonly Priority Medium = new(2);
   public static readonly Priority High = new(3);
}
```

--------------------------------

### FileUrn usage: create, parse, validate, and serialize

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects

Shows typical usage of FileUrn: creating instances with Create, parsing from string via IParsable.Parse, handling FormatException for invalid formats, and serializing/deserializing with System.Text.Json. The output comments indicate expected results, including equality after parsing and JSON serialization to the string format.

```csharp
// Creating a FileUrn from its components
var documentLocation = FileUrn.Create("blob storage", "containers/documents/contract.pdf");
var imageLocation = FileUrn.Create("local file system", "images/profile/user123.jpg");

// Parsing from string
var parsed = FileUrn.Parse("blob storage:containers/documents/contract.pdf", null);       // IParsable.Parse
Console.WriteLine($"parsed file urn: {parsed}");                                  // { FileStore = blob storage, Urn = containers/documents/contract.pdf }
Console.WriteLine($"documentLocation == parsed: {documentLocation == parsed}"); // true

// Validation
try
{
   var invalid = FileUrn.Parse("invalid-format", null);
}
catch (FormatException ex)
{
   Console.WriteLine(ex.Message); // "Invalid FileUrn format. Expected 'fileStore:urn'"
}

// Serialization
var json = JsonSerializer.Serialize(documentLocation);
Console.WriteLine($"Serialized JSON: {json}"); // "blob storage:containers/documents/contract.pdf"

var deserialized = JsonSerializer.Deserialize<FileUrn>(json);
Console.WriteLine($"Deserialized FileUrn: {deserialized}"); // blob storage:containers/documents/contract.pdf
```

--------------------------------

### Using the Smart Enum to import CSV

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows how to use the SalesCsvImporterType smart enum to read a CSV file, extracting article ID, volume, and datetime without a switch-case.

```csharp
var type = SalesCsvImporterType.Monthly;
var csv = ...;

using var textReader = new StringReader(csv);
using var csvReader = new CsvReader(textReader, new CsvConfiguration(CultureInfo.InvariantCulture) { HasHeaderRecord = true });

csvReader.Read();
csvReader.ReadHeader();

while (csvReader.Read())
{
   var articleId = csvReader.GetField<int>(type.ArticleIdIndex);
   var volume = csvReader.GetField<decimal>(type.VolumeIndex);
   var dateTime = type.GetDateTime(csvReader);

   Console.WriteLine($"CSV ({type}): Article-Id={articleId}, DateTime={dateTime}, Volume={volume}");
}
```

--------------------------------

### Model validation error response

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Value-Objects-Framework-Integration

Example JSON error response returned when a value object validation fails, e.g., when a product name is rejected. The client receives a BadRequest (400) status with this error body.

```json
{
  "productName": [
    "Product name cannot be 1 character long."
  ]
}
```

--------------------------------

### Create single-item collections with SingleItem.Dictionary, Lookup, and Set

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/SingleItem

Shows the three factory methods on SingleItem for creating single-item collections: Dictionary, Lookup, and Set. Use these to avoid allocating a full collection when only one element is needed.

```C#
IReadOnlyDictionary<int, string> dictionary = SingleItem.Dictionary(42, "name");

ILookup<int, string> lookup = SingleItem.Lookup(42, new[] { "name", "other name" });

IReadOnlySet<string> set = SingleItem.Set("name");
```

--------------------------------

### Use Empty.Action for Action and Action<string> parameters

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Empty-...

Shows how to pass Empty.Action to methods expecting Action or Action<string> delegates. The comment notes that Empty.Action provides an empty Action for MyMethod_1 and an empty Action<string> for MyMethod_2.

```C#
public static void Main()
{
	MyMethod_1(Empty.Action); // provides MyMethod_1 with an empty "Action"
	MyMethod_2(Empty.Action); // provides MyMethod_2 with an empty "Action<string>"
}

private static void MyMethod_1(Action action)
{
	...
}

private static void MyMethod_2(Action<string> action)
{
	...
}
```

--------------------------------

### Print all items using T.Items

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Use T.Items to get all items of a smart enum type. The generic method PrintAllItems<T, TKey> constrains T to ISmartEnum<TKey, T, ValidationError> and TKey to notnull, then iterates over T.Items to print each item.

```csharp
// Use T.Items to get all items.
PrintAllItems<ProductType, string>();

private static void PrintAllItems<T, TKey>()
   where T : ISmartEnum<TKey, T, ValidationError>
   where TKey : notnull
{
   Console.WriteLine($"Print all items of '{typeof(T).Name}':");

   foreach (T item in T.Items)
   {
      Console.WriteLine($"Item: {item}");
   }
}
```

--------------------------------

### MessageProcessorType Usage

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions

Demonstrates how to invoke the processor and handle the result exhaustively using the Switch method.

```csharp
var processorType = MessageProcessorType.Email;

ProcessingResult result = processorType.Process("Your order shipped!");

// Handle result — compile-time exhaustive
result.Switch(
    success: success => Handle(success.TransactionId, success.Timestamp),
    failure: failure => Handle(failure.ErrorMessage)
);
```

--------------------------------

### SwitchPartially with state passing

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows how to pass a logger as state to SwitchPartially to prevent closures, using static lambdas.

```csharp
ILogger logger = ...;

// SwitchPartially with state
productType.SwitchPartially(
    logger,
    @default: static (l, item) => l.LogInformation("Default: {Item}", item),
    electronics: static l => l.LogInformation("Electronics specific logic")
);
```

--------------------------------

### Generic Key with INumber<T> Constraint

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Shows a generic-key Smart Enum constrained to INumber<T>, which enables generation of IParsable, ISpanParsable, IComparable, IFormattable, and comparison operators. The example uses T.Zero and T.One as keys and demonstrates the generated Parse method.

```csharp
[SmartEnum<TypeParamRef1>]
public partial class Metric<T>
   where T : INumber<T>
{
   public static readonly Metric<T> Temperature = new(T.Zero);
   public static readonly Metric<T> Humidity = new(T.One);
}

// IParsable<Metric<int>> is generated because INumber<int> implements IParsable<int>
var m = Metric<int>.Parse("0", null);
```

--------------------------------

### Persist discriminated unions with EF Core (TPH)

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions-Framework-Integration

Complete EF Core example: entity and union definitions, entity type configurations for TPH with discriminator, SQL Server schema, and usage showing state transitions and Switch pattern matching.

```csharp
public class Message
{
   public required Guid Id { get; init; }
   public required List<MessageState> States { get; set; }
}

[Union]
public abstract partial record MessageState
{
   public int Order { get; } // auto-incremented PK

   public sealed record Initial : MessageState;
   public sealed record Parsed(DateTime CreatedAt) : MessageState;
   public sealed record Processed(DateTime CreatedAt) : MessageState;
   public sealed record Error(string Message) : MessageState;
}
```

```csharp
public class MessageEntityTypeConfiguration : IEntityTypeConfiguration<Message>
{
   public void Configure(EntityTypeBuilder<Message> builder)
   {
      builder.ToTable("Messages");

      builder.HasMany(m => m.States)
             .WithOne()
             .HasForeignKey("MessageId");

      builder.Navigation(m => m.States).AutoInclude();
   }
}

public class MessageStateEntityTypeConfiguration
   : IEntityTypeConfiguration<MessageState>,
     IEntityTypeConfiguration<MessageState.Parsed>,
     IEntityTypeConfiguration<MessageState.Processed>
{
   public void Configure(EntityTypeBuilder<MessageState> builder)
   {
      builder.ToTable("MessageStates");

      builder.HasKey(s => s.Order);

      builder.Property(s => s.Order).ValueGeneratedOnAdd(); // auto-increment
      builder.Property<Guid>("MessageId"); // FK to the message table (as a shadow property)

      builder
         .HasDiscriminator<string>("Type")
         .HasValue<MessageState.Initial>("Initial")
         .HasValue<MessageState.Parsed>("Parsed")
         .HasValue<MessageState.Processed>("Processed")
         .HasValue<MessageState.Error>("Error");
   }

   public void Configure(EntityTypeBuilder<MessageState.Parsed> builder)
   {
      builder.Property(s => s.CreatedAt).HasColumnName("CreatedAt");
   }

   public void Configure(EntityTypeBuilder<MessageState.Processed> builder)
   {
      builder.Property(s => s.CreatedAt).HasColumnName("CreatedAt");
   }
}
```

```sql
CREATE TABLE [Messages]
(
    [Id] uniqueidentifier NOT NULL,
    CONSTRAINT [PK_Messages] PRIMARY KEY ([Id])
);

CREATE TABLE [MessageStates]
(
    [Order]     int              NOT NULL IDENTITY,
    [MessageId] uniqueidentifier NOT NULL,
    [Type]      nvarchar(13)     NOT NULL,
    [Message]   nvarchar(max)    NULL,
    [CreatedAt] datetime2        NULL,
    CONSTRAINT [PK_MessageStates] PRIMARY KEY ([Order]),
    CONSTRAINT [FK_MessageStates_Messages_MessageId] FOREIGN KEY ([MessageId]) REFERENCES [Messages] ([Id]) ON DELETE CASCADE
);
```

```csharp
var message = new Message
              {
                 Id = Guid.NewGuid(),
                 States = [new MessageState.Initial()]
              };
ctx.Messages.Add(message);
await ctx.SaveChangesAsync();

ctx.ChangeTracker.Clear(); // remove message from the EF context

// Message states: [{"Order": 1, "$type": "Initial"}]
message = await ctx.Messages.SingleAsync();
logger.LogInformation("Message states: {@States}", message.States);

// Trasition to "Parsed" state
message.States.Add(new MessageState.Parsed(DateTime.Now));
await ctx.SaveChangesAsync();

ctx.ChangeTracker.Clear(); // remove message from the EF context

// Message states: [{"Order": 1, "$type": "Initial"}, {"CreatedAt": "2025-03-16T10:53:35.7020302", "Order": 2, "$type": "Parsed"}]
message = await ctx.Messages.SingleAsync();
logger.LogInformation("Message states: {@States}", message.States);

var currentState = message.States.OrderBy(s => s.Order).Last();

// Parsed (at 03/16/2025 10:52:35)
currentState.Switch(
   initial: _ => logger.LogInformation("Initial state"),
   parsed: s => logger.LogInformation("Parsed (at {ParsedAt})", s.CreatedAt),
   processed: s => logger.LogInformation("Processed (at {ProcessedAt})", s.CreatedAt),
   error: s => logger.LogInformation("Error: {Error}", s.Message)
);
```

--------------------------------

### Generic Key Types with TypeParamRef1

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Demonstrates a Smart Enum with a generic key type using TypeParamRef1. The type parameter must have a notnull constraint (or struct/class) to avoid analyzer error TTRESG074. Shows usage with Get, TryGet, and Items for an int key.

```csharp
using Thinktecture;

[SmartEnum<TypeParamRef1>]
public partial class Priority<T>
   where T : notnull
{
   public static readonly Priority<T> Low;
   public static readonly Priority<T> Medium;
   public static readonly Priority<T> High;
}

// Usage with int key
Priority<int> p = Priority<int>.Get(1);

if (Priority<int>.TryGet(99, out var unknown))
{
    Console.WriteLine("Found");
}

// Iterate all items
foreach (var item in Priority<int>.Items)
{
    Console.WriteLine(item);
}
```

--------------------------------

### Type conversion, equality, and TypeConverter for SmartEnum

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Smart-Enums

Demonstrates implicit conversion to the key type, equality using reference equality (items are singletons), and operator overloading. GetHashCode delegates to the key using the configured equality comparer (default OrdinalIgnoreCase for strings). ToString delegates to the key's ToString(). TypeConverter support allows conversion to and from the key type via TypeDescriptor.

```csharp
// Implicit conversion to key type
string key = ProductType.Electronics;  // Returns "Electronics"

// Equality comparison - uses reference equality (items are singletons)
bool areEqual = ProductType.Electronics.Equals(ProductType.Electronics);
bool areEqualOp = ProductType.Electronics == ProductType.Electronics;  // Operator overloading
bool notEqual = ProductType.Electronics != ProductType.Clothing;

// GetHashCode - delegates to the key using the configured equality comparer
// (default: OrdinalIgnoreCase for strings, default comparer for other types)
int hashCode = ProductType.Electronics.GetHashCode();

// ToString - delegates to the key's ToString()
string name = ProductType.Electronics.ToString();  // Returns "Electronics"

// TypeConverter
var converter = TypeDescriptor.GetConverter(typeof(ProductType));
string? keyStr = (string?)converter.ConvertTo(ProductType.Electronics, typeof(string));
ProductType? converted = (ProductType?)converter.ConvertFrom("Electronics");
```

--------------------------------

### Basic generic ad hoc union with TypeParamRef placeholders

Source: https://github.com/pawelgerr/thinktecture.runtime.extensions/wiki/Discriminated-Unions

Defines a generic union `Either<T1, T2>` using TypeParamRef1 and TypeParamRef2. Type parameter members do not get implicit conversion operators, so use constructors or factory methods like CreateT2.

```csharp
using Thinktecture;

[Union<TypeParamRef1, TypeParamRef2>]
public partial struct Either<T1, T2>;

// Usage — type parameter members don't get implicit conversion operators,
// use constructors or factory methods instead
Either<string, int> value = new Either<string, int>("hello");        // constructor
Either<string, int> number = Either<string, int>.CreateT2(42);       // factory method
```
Tokens:
Raw