Thinktecture.Runtime.Extensions.Newtonsoft.Json 8.5.4

There is a newer version of this package available.
See the version list below for details.
dotnet add package Thinktecture.Runtime.Extensions.Newtonsoft.Json --version 8.5.4
                    
NuGet\Install-Package Thinktecture.Runtime.Extensions.Newtonsoft.Json -Version 8.5.4
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Thinktecture.Runtime.Extensions.Newtonsoft.Json" Version="8.5.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Thinktecture.Runtime.Extensions.Newtonsoft.Json" Version="8.5.4" />
                    
Directory.Packages.props
<PackageReference Include="Thinktecture.Runtime.Extensions.Newtonsoft.Json" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Thinktecture.Runtime.Extensions.Newtonsoft.Json --version 8.5.4
                    
#r "nuget: Thinktecture.Runtime.Extensions.Newtonsoft.Json, 8.5.4"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#addin nuget:?package=Thinktecture.Runtime.Extensions.Newtonsoft.Json&version=8.5.4
                    
Install Thinktecture.Runtime.Extensions.Newtonsoft.Json as a Cake Addin
#tool nuget:?package=Thinktecture.Runtime.Extensions.Newtonsoft.Json&version=8.5.4
                    
Install Thinktecture.Runtime.Extensions.Newtonsoft.Json as a Cake Tool

Build TestResults NuGet Downloads

Thinktecture.Runtime.Extensions
Thinktecture.Runtime.Extensions.EntityFrameworkCore6
Thinktecture.Runtime.Extensions.EntityFrameworkCore7
Thinktecture.Runtime.Extensions.EntityFrameworkCore8
Thinktecture.Runtime.Extensions.EntityFrameworkCore9
Thinktecture.Runtime.Extensions.Json
Thinktecture.Runtime.Extensions.Newtonsoft.Json
Thinktecture.Runtime.Extensions.MessagePack
Thinktecture.Runtime.Extensions.AspNetCore

This library provides some interfaces, classes, Roslyn Source Generators, Roslyn Analyzers and Roslyn CodeFixes for implementation of Smart Enums, Value Objects and Discriminated Unions.

Documentation

See wiki for more documentation.

Requirements

  • Version 8:
    • C# 11 (or higher) for generated code
    • SDK 8.0.400 (or higher) for building projects
  • Version 7:
    • C# 11 (or higher) for generated code
    • SDK 7.0.401 (or higher) for building projects

Migrations

Ideas and real-world use cases

Smart Enums:

Value objects:

Discriminated Unions:

Smart Enums

Smart Enums provide a powerful alternative to traditional C# enums, offering type-safety, extensibility, and rich behavior. Unlike regular C# enums which are limited to numeric values and lack extensibility, Smart Enums can:

  • Use any type as the underlying type (e.g., strings, integers) or none at all
  • Include additional fields, properties and behavior
  • Use polymorphism to define custom behavior for each value
  • Prevent creation of invalid values
  • Integrate seamlessly with JSON serializers, MessagePack, Entity Framework Core and ASP.NET Core

Install: Install-Package Thinktecture.Runtime.Extensions

Documentation: Smart Enums

Some of the Key Features are:

  • Choice between always-valid and maybe-valid Smart Enum
  • Reflection-free iteration over all items
  • Fast lookup/conversion from underlying type to Smart Enum and vice versa
  • Allows custom properties and methods
  • Exhaustive pattern matching with Switch/Map methods
  • Provides appropriate constructor, based on the specified properties/fields
  • Proper implementation of Equals, GetHashCode, ToString and equality operators
  • Provides implementation of IComparable, IComparable<T>, IFormattable, IParsable<T> and comparison operators <, <=, >, >= (if applicable to the underlying type)
  • Custom comparer and equality comparer

Roslyn Analyzers and CodeFixes help the developers to implement the Smart Enums correctly

Provides support for:

  • JSON (System.Text.Json and Newtonsoft)
  • Minimal Api Parameter Binding and ASP.NET Core Model Binding
  • Entity Framework Core
  • MessagePack

Definition of a Smart Enum with custom properties and methods.

[SmartEnum<string>]
public partial class ShippingMethod
{
   public static readonly ShippingMethod Standard = new(
      "STANDARD",
      basePrice: 5.99m,
      weightMultiplier: 0.5m,
      estimatedDays: 5,
      requiresSignature: false);

   public static readonly ShippingMethod Express = new(
      "EXPRESS",
      basePrice: 15.99m,
      weightMultiplier: 0.75m,
      estimatedDays: 2,
      requiresSignature: true);

   public static readonly ShippingMethod NextDay = new(
      "NEXT_DAY",
      basePrice: 29.99m,
      weightMultiplier: 1.0m,
      estimatedDays: 1,
      requiresSignature: true);

   private readonly decimal _basePrice;
   private readonly decimal _weightMultiplier;
   private readonly int _estimatedDays;

   public bool RequiresSignature { get; }

   public decimal CalculatePrice(decimal orderWeight)
   {
      return _basePrice + (orderWeight * _weightMultiplier);
   }

   public DateTime GetEstimatedDeliveryDate()
   {
      return DateTime.Today.AddDays(_estimatedDays);
   }
}

Behind the scenes a Roslyn Source Generator generates additional code. Some of the features that are now available are ...

Basic Operations

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

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

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

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

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

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

// IComparable
int comparison = ProductGroup.Fruits.CompareTo(ProductGroup.Vegetables);
bool isGreater = ProductGroup.Fruits > ProductGroup.Vegetables;  // Comparison operators

Type Conversion and Equality

// Implicit conversion to key type
string key = ProductType.Groceries;  // Returns "Groceries"

// Equality comparison
bool equal = ProductType.Groceries.Equals(ProductType.Groceries);
bool equal = ProductType.Groceries == ProductType.Groceries;  // Operator overloading
bool notEqual = ProductType.Groceries != ProductType.Housewares;

// Methods inherited from Object
int hashCode = ProductType.Groceries.GetHashCode();
string key = ProductType.Groceries.ToString();  // Returns "Groceries"

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

Pattern Matching with Switch/Map

All Switch/Map methods are exhaustive by default ensuring all cases are handled correctly.

ProductType productType = ProductType.Groceries;

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

// Transform enum values into different types
string department = productType.Switch(
    groceries: () => "Food and Beverages",
    housewares: () => "Home and Kitchen"
);

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

For optimal performance Smart Enums provide overloads that prevent closures.

ILogger logger = ...;

// Prevent closures by passing the parameter as first method argument
productType.Switch(logger,
    groceries: static l => l.LogInformation("Processing groceries order"),
    housewares: static l => l.LogInformation("Processing housewares order")
);

// Use a tuple to pass multiple values
var context = (Logger: logger, OrderId: "123");

productType.Switch(context,
    groceries: static ctx => ctx.Logger.LogInformation("Processing groceries order {OrderId}", ctx.OrderId),
    housewares: static ctx => ctx.Logger.LogInformation("Processing housewares order {OrderId}", ctx.OrderId)
);

Value Objects

Install: Install-Package Thinktecture.Runtime.Extensions

Documentation: Value Objects

Value objects help solve several common problems in software development:

  1. Type Safety: Prevent mixing up different concepts that share the same primitive type

    // Problem: Easy to accidentally swap parameters
    void ProcessOrder(int customerId, int orderId) { ... }
    ProcessOrder(orderId, customerId); // Compiles but wrong!
    
    // Solution: Value objects make it type-safe
    [ValueObject<int>]
    public partial struct CustomerId { }
    
    [ValueObject<int>]
    public partial struct OrderId { }
    
    void ProcessOrder(CustomerId customerId, OrderId orderId) { ... }
    ProcessOrder(orderId, customerId); // Won't compile!
    
  2. Built-in Validation: Ensure data consistency at creation time

    [ValueObject<decimal>]
    public partial struct Amount
    {
        static partial void ValidateFactoryArguments(ref ValidationError? validationError, ref decimal value)
        {
            if (value < 0)
            {
                validationError = new ValidationError("Amount cannot be negative");
                return;
            }
            // Normalize to two decimal places
            value = Math.Round(value, 2);
        }
    }
    
    var amount = Amount.Create(100.50m);     // Success: 100.50
    var invalid = Amount.Create(-50m);       // Throws ValidationException
    
  3. Immutability: Prevent accidental modifications and ensure thread safety

  4. Complex Value Objects: Encapsulate multiple related values with validation

    [ComplexValueObject]
    public sealed partial class DateRange
    {
        public DateOnly Start { get; }
        public DateOnly End { get; }
    
        static partial void ValidateFactoryArguments(
            ref ValidationError? validationError,
            ref DateOnly start,
            ref DateOnly end)
        {
            if (end < start)
            {
                validationError = new ValidationError(
                    $"End date '{end}' cannot be before start date '{start}'");
                return;
            }
    
            // Ensure dates are not in the past
            var today = DateOnly.FromDateTime(DateTime.Today);
            if (start < today)
            {
                validationError = new ValidationError("Start date cannot be in the past");
                return;
            }
        }
    
        public int DurationInDays => End.DayNumber - Start.DayNumber + 1;
    
        public bool Contains(DateOnly date) => date >= Start && date <= End;
    }
    
    // Usage
    var range = DateRange.Create(
        start: DateOnly.FromDateTime(DateTime.Today),
        end: DateOnly.FromDateTime(DateTime.Today.AddDays(7))
    );
    
    Console.WriteLine(range.DurationInDays);    // 8
    Console.WriteLine(range.Contains(range.Start));  // true
    

Key Features:

  • Two types of value objects:
    • Simple value objects (wrapper around a single value with validation)
    • Complex value objects (multiple properties representing a single concept)
  • Comprehensive validation support with descriptive error messages
  • Framework integration:
    • JSON serialization (System.Text.Json and Newtonsoft.Json)
    • Entity Framework Core support
    • ASP.NET Core Model Binding
    • MessagePack serialization
  • Rich feature set:
    • Type conversion and comparison operators
    • Custom equality comparison
    • Proper implementation of standard interfaces (IComparable, IFormattable, etc.)
    • Configurable null and empty string handling
  • Development support:
    • Roslyn Analyzers and CodeFixes for correct implementation
    • Logging for debugging and insights

For more examples and detailed documentation, see the wiki.

Discriminated Unions

Install: Install-Package Thinktecture.Runtime.Extensions

Documentation: Discriminated Unions

Discriminated unions are a powerful feature that allows a type to hold a value that could be one of several different types. They provide type safety, exhaustive pattern matching, and elegant handling of complex domain scenarios. Key benefits include:

  • Type-safe representation of values that can be one of several types
  • Exhaustive pattern matching ensuring all cases are handled
  • Elegant modeling of domain concepts with multiple states
  • Clean handling of success/failure scenarios without exceptions

The library provides two types of unions to suit different needs:

Ad hoc unions

Perfect for simple scenarios where you need to combine a few types quickly. Features:

  • Type-safe combination of up to 5 different types
  • Implicit conversions and type checking
  • Exhaustive pattern matching with Switch/Map methods
  • Built-in equality comparison
  • Support for class, struct, or ref struct implementations
// Quick combination of types
[Union<string, int>]
public partial class TextOrNumber;

// Create and use the union
TextOrNumber value = "Hello";           // Implicit conversion
TextOrNumber number = 42;               // Works with any defined type

// Type-safe access
if (value.IsString)
{
    string text = value.AsString;       // Type-safe access
    Console.WriteLine(text);
}

// Exhaustive pattern matching
var result = value.Switch(
    @string: text => $"Text: {text}",
    int32: num => $"Number: {num}"
);

// Custom property names for clarity
[Union<string, int>(T1Name = "Text", T2Name = "Number")]
public partial class BetterNamed;
// Now use .IsText, .IsNumber, .AsText, .AsNumber

Regular unions

Ideal for modeling domain concepts and complex hierarchies. Features:

  • Inheritance-based approach for complex scenarios
  • Support for both classes and records
  • Integration with value objects
  • Generic type support
  • Exhaustive pattern matching

Perfect for modeling domain concepts:

// Model domain concepts clearly
[Union]
public partial record OrderStatus
{
    public record Pending : OrderStatus;
    public record Processing(DateTime StartedAt) : OrderStatus;
    public record Completed(DateTime CompletedAt, string TrackingNumber) : OrderStatus;
    public record Cancelled(string Reason) : OrderStatus;
}

// Generic result type for error handling
[Union]
public partial record Result<T>
{
    public record Success(T Value) : Result<T>;
    public record Failure(string Error) : Result<T>;

    // Convenient implicit conversions
    public static implicit operator Result<T>(T value) => new Success(value);
    public static implicit operator Result<T>(string error) => new Failure(error);
}

// Usage
Result<int> result = await GetDataAsync();
var message = result.Switch(
    success: s => $"Got value: {s.Value}",
    failure: f => $"Error: {f.Error}"
);
Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
9.1.0 59 5/23/2025
9.0.1 120 5/21/2025
9.0.0 127 5/11/2025
8.10.0 57 5/23/2025
8.9.2 106 5/21/2025
8.9.1 126 5/8/2025
8.9.0 129 5/7/2025
8.8.1 130 5/4/2025
8.8.0 123 4/27/2025
8.8.0-beta02 147 4/22/2025
8.8.0-beta01 137 4/21/2025
8.7.0 183 4/16/2025
8.7.0-beta03 175 4/15/2025
8.7.0-beta02 146 4/10/2025
8.7.0-beta01 147 4/9/2025
8.6.1 295 4/2/2025
8.6.0 82 3/29/2025
8.5.5 131 3/27/2025
8.5.4 517 3/24/2025
8.5.3 141 3/13/2025
8.5.2 146 3/12/2025
8.5.1 169 3/8/2025
8.5.0 213 3/4/2025
8.5.0-beta01 83 2/26/2025
8.4.1 96 2/24/2025
8.4.0 97 2/23/2025
8.3.0 103 2/16/2025
8.2.0 113 1/23/2025
8.1.0 107 1/17/2025
8.0.2 121 12/18/2024
8.0.1 107 12/11/2024
8.0.0 104 12/9/2024
8.0.0-beta13 92 11/21/2024
8.0.0-beta12 72 11/19/2024
8.0.0-beta11 79 11/15/2024
8.0.0-beta10 87 10/25/2024
8.0.0-beta09 90 10/23/2024
8.0.0-beta08 94 10/23/2024
8.0.0-beta07 116 9/27/2024
8.0.0-beta06 69 9/19/2024
8.0.0-beta05 97 9/9/2024
8.0.0-beta04 93 9/9/2024
8.0.0-beta03 84 9/8/2024
8.0.0-beta02 94 9/3/2024
8.0.0-beta01 119 8/13/2024
7.6.1 104 11/21/2024
7.6.0 106 11/13/2024
7.5.3 2,038 10/23/2024
7.5.2 829 9/27/2024
7.5.1 295 9/5/2024
7.5.0 800 7/9/2024
7.4.0 409 6/13/2024
7.3.0 150 4/18/2024
7.2.1 145 4/14/2024
7.2.0 140 1/31/2024
7.1.0 1,389 12/11/2023
7.0.0 143 12/10/2023
7.0.0-beta10 122 11/30/2023
7.0.0-beta09 127 11/26/2023
7.0.0-beta08 126 11/19/2023
7.0.0-beta07 123 11/17/2023
7.0.0-beta06 120 11/14/2023
7.0.0-beta05 116 11/14/2023
7.0.0-beta04 107 11/7/2023
7.0.0-beta03 127 10/19/2023
7.0.0-beta02 124 10/10/2023
7.0.0-beta01 127 10/8/2023
6.6.0 175 11/30/2023
6.5.2 143 11/17/2023
6.5.1 110 11/11/2023
6.5.0 136 11/11/2023
6.5.0-beta03 119 11/6/2023
6.5.0-beta02 116 11/5/2023
6.5.0-beta01 101 11/5/2023
6.4.1 148 11/9/2023
6.4.0 1,896 9/3/2023
6.3.0 169 8/31/2023
6.2.0 1,571 4/2/2023
6.1.0 246 3/22/2023
6.1.0-beta02 163 3/19/2023
6.1.0-beta01 161 3/19/2023
6.0.1 272 3/12/2023
6.0.0 260 3/9/2023
6.0.0-beta03 166 3/6/2023
6.0.0-beta02 157 3/5/2023
6.0.0-beta01 160 3/2/2023
5.2.0 720 2/6/2023
5.1.0 831 11/25/2022
5.0.1 827 10/6/2022
5.0.0 447 9/28/2022
5.0.0-beta03 175 9/7/2022
5.0.0-beta02 164 9/4/2022
5.0.0-beta01 175 9/4/2022
4.4.0-beta02 176 8/31/2022
4.4.0-beta01 163 8/30/2022
4.3.3 459 8/17/2022
4.3.3-beta01 184 8/17/2022
4.3.2 742 6/15/2022
4.3.2-beta02 174 6/15/2022
4.3.2-beta01 194 5/18/2022
4.3.1 958 5/17/2022
4.3.0 477 5/16/2022
4.2.0 494 4/24/2022
4.2.0-beta01 209 4/23/2022
4.1.3 490 4/13/2022
4.1.2 1,400 2/10/2022
4.1.1 518 2/6/2022
4.1.0 507 2/5/2022
4.0.1 528 1/16/2022
4.0.0 495 1/14/2022
4.0.0-beta03 254 12/17/2021
4.0.0-beta02 235 12/14/2021
4.0.0-beta01 239 12/13/2021
3.1.0 444 9/25/2021
3.0.0 496 7/10/2021
3.0.0-beta10 346 7/10/2021
3.0.0-beta09 254 4/1/2021
3.0.0-beta08 263 3/15/2021
3.0.0-beta07 275 3/14/2021
3.0.0-beta06 320 3/11/2021
3.0.0-beta05 270 2/12/2021
3.0.0-beta04 256 2/7/2021
3.0.0-beta03 291 1/30/2021
3.0.0-beta02 281 1/11/2021
3.0.0-beta01 327 1/10/2021
2.1.0-beta02 346 11/6/2020
2.0.1 5,675 10/8/2019
2.0.0 553 10/8/2019
2.0.0-beta02 423 10/8/2019
2.0.0-beta01 448 9/30/2019
1.2.0 653 9/29/2019
1.2.0-beta04 689 8/29/2019
1.2.0-beta03 462 8/26/2019
1.2.0-beta02 498 8/12/2019
1.2.0-beta01 485 8/4/2019