Sstv.PartialUpdate 1.0.0

Sstv.PartialUpdate

A Roslyn source generator that automatically creates *Changes classes for partial entity updates in .NET applications.

Overview

Sstv.PartialUpdate generates change-tracking classes from your entities, enabling partial updates without manually creating separate DTOs. Perfect for PATCH APIs and scenarios where you need to update only specific fields.

Features

• Automatic Code Generation: Generates *Changes classes from entities with [PartialUpdatable] attribute
• Partial Updates: Track which fields were modified without sending the entire entity
• Flexible JSON Parsing: Supports both numeric and string values for numeric types
• Validation: Built-in null checking and type validation
• Unread Changes Detection: Optional verification that all received changes were processed
• Nullable Support: Full support for nullable reference and value types
• Case Insensitive: Property name matching is case-insensitive

Installation

dotnet add package Sstv.PartialUpdate

Quick Start

1. Mark your entity properties

using Sstv.PartialUpdate;

public partial class User
{
    [PartialUpdatable]
    public string Name { get; set; } = string.Empty;

    [PartialUpdatable]
    public int Age { get; set; }

    [PartialUpdatable]
    public string? Email { get; set; }
}

2. Use the generated Changes class

using System.Text.Json;

// Parse JSON patch document
var json = """
    {
        "name": "John Doe",
        "age": 30
    }
    """;
var changes = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(json);

// Create changes object
var userChanges = UserChanges.From(changes);

// Check if a field was provided
if (userChanges.Name.IsDefined)
{
    Console.WriteLine($"New name: {userChanges.Name.Value}");
}

// Verify all fields were processed
userChanges.VerifyNoUnreadChanges();

Supported Types

• Primitives: int, long, short, byte, sbyte, uint, ushort, ulong
• Floating Point: float, double, decimal
• Other: bool, string, Guid, DateTime, DateTimeOffset, TimeSpan
• Arrays: byte[] (supports both Base64 string and JSON array formats)
• Collections: List<T>, arrays of any supported type
• Complex Types: Nested classes, records, structs implementing IParsable<TSelf>
• Enums: Standard enums and nullable enums
• Nullable: Full support for all nullable types

Advanced Usage

Skip unknown values

var result = UserChanges.From(changes, skipUnknownValues: true);

Non-nullable strings (throws on null)

[PartialUpdatable]
public string RequiredName { get; set; } = string.Empty;

// This will throw InvalidOperationException if null is passed

Verify unread changes

var changes = UserChanges.From(jsonDict);

// Process some fields...
var name = changes.Name.Value;

// This throws if 'age' was provided but not read
changes.VerifyNoUnreadChanges();

Configuration

The generated code includes:

• AllProperties: Static HashSet<string> containing all updatable property names
• SerializerOptions: Pre-configured JsonSerializerOptions with camelCase naming

Requirements

• .NET Standard 2.0+ (works with .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+)
• C# 10+

How It Works

The source generator runs at compile time and:

1. Scans for classes with [PartialUpdatable] annotated properties
2. Generates a partial *Changes class with Optional<T> properties for each marked field
3. Creates a static From(Dictionary<string, JsonElement>) method for parsing JSON
4. Adds helper methods like VerifyNoUnreadChanges()

License

MIT License