Kassyi.Generators.DependencyProperty 1.0.0-preview.4

Kassyi.Generators.DependencyProperty

English | 日本語

The Kassyi.Generators.DependencyProperty is a zero-allocation, highly optimized generator for dotnet/runtime-scale codebases. It delivers microsecond-tier throughput and supports WPF, UWP, WinUI, Uno, Avalonia, and MAUI.

Why this fork?

This project is an independently maintained, highly optimized fork of HavenDV/DependencyPropertyGenerator. We re-architected the generator to eliminate critical silent failures (such as emitting propertyChangedCallback: null without warnings, as seen in HavenDV#165), enforce strict compile-time type safety, and deliver up to 30% faster code generation (+62.4% overall throughput score) with zero Gen2 allocations.

Zero-Allocation & No IDE Lag

Incremental source generators run continuously in the background on every keystroke. Heavy memory allocations in the original generator triggered Gen2 garbage collections, causing noticeable typing lag in IDEs like Visual Studio and JetBrains Rider.

We rebuilt the pipeline to maximize throughput:

• Zero Gen2 GC Pauses: Reduces memory allocations by ~22% (saving ~650 KB per class) to completely eliminate Gen2 GC pauses.
• Optimized Pipeline: Replaces expensive AST round-trips (NormalizeWhitespace()) with direct, zero-allocation formatted streaming.
• Zero-Allocation Scopes: Implements custom ref struct scope handlers (ClassScope) to prevent intermediate string allocations.
• Declarative Rule Engine: Shifts from runtime string parsing to compile-time semantic flag analysis.

<details> <summary><b>View Benchmark Results (AMD Ryzen 9 7900X / .NET 9)</b></summary>

</details>

Critical Bug Fixes & Enhancements

• Strict Type Safety (#error DPG0001 / DPG0007): The original generator silently failed (HavenDV#165), emitting propertyChangedCallback: null without diagnostic errors for invalid OnChanged callbacks. This fork immediately surfaces signature mismatches as compile-time errors.
• Target-Typed new(...) Expansion: Supports C# 9.0+ DefaultValueExpression = "new(...)". The generator automatically expands these into fully-qualified constructors to remove verbose type names.
• Modular Architecture: Decouples monolithic logic into modular framework strategies (WPF, WinUI, Avalonia, etc.) to improve maintainability and testability.
• Package Renaming: Publishes as Kassyi.Generators.DependencyProperty to provide a clean namespace and prevent collisions.

Installation

Install the package via the .NET CLI or NuGet Package Manager:

dotnet add package Kassyi.Generators.DependencyProperty

Or add the package reference directly to your .csproj:

<PackageReference Include="Kassyi.Generators.DependencyProperty" Version="0.1.0" PrivateAssets="all" />

Quick Start

Define your properties using generic attributes. The generator automatically wires up the boilerplate.

using DependencyPropertyGenerator;
using System.Windows.Controls;

#nullable enable

namespace MyApp.Controls;

[DependencyProperty<bool>("IsSpinning", DefaultValue = true, Category = "Category", Description = "Description")]
public partial class MyControl : UserControl
{
    // Optional callback, automatically wired up by the generator
    partial void OnIsSpinningChanged(bool oldValue, bool newValue)
    {
    }
}

[AttachedDependencyProperty<object, TreeView>("SelectedItem", DefaultBindingMode = DefaultBindingMode.TwoWay)]
public static partial class TreeViewExtensions
{
    // Optional callback, automatically wired up by the generator
    static partial void OnSelectedItemChanged(TreeView sender, object? oldValue, object? newValue)
    {
    }
}

<details> <summary><b>View the generated code</b></summary>

// HintName: MyControl.Properties.IsSpinning.generated.cs
#nullable enable

namespace MyApp.Controls
{
    public partial class MyControl
    {
        public static readonly global::System.Windows.DependencyProperty IsSpinningProperty =
            global::System.Windows.DependencyProperty.Register(
                name: "IsSpinning",
                propertyType: typeof(bool),
                ownerType: typeof(global::MyApp.Controls.MyControl),
                typeMetadata: new global::System.Windows.FrameworkPropertyMetadata(
                    defaultValue: (bool)true,
                    flags: global::System.Windows.FrameworkPropertyMetadataOptions.None,
                    propertyChangedCallback: static (sender, args) =>
                    {
                        ((global::MyApp.Controls.MyControl)sender).OnIsSpinningChanged(
                            (bool)args.OldValue,
                            (bool)args.NewValue);
                    }));

        [global::System.ComponentModel.Category("Category")]
        [global::System.ComponentModel.Description("Description")]
        public bool IsSpinning
        {
            get => (bool)GetValue(IsSpinningProperty);
            set => SetValue(IsSpinningProperty, value);
        }

        partial void OnIsSpinningChanged();
        partial void OnIsSpinningChanged(bool newValue);
        partial void OnIsSpinningChanged(bool oldValue, bool newValue);
    }
}

(Note: Code shortened for brevity)

</details>

Advanced Features

Target-Typed new(...) in Default Values

You can cleanly define default values using C# 9.0+ target-typed new() expressions. The generator safely expands it to the full type:

public readonly record struct Data(int Value);

// Automatically expands to the property's type (new global::MyNamespace.Data(42))
[AttachedDependencyProperty<Data, TreeView>("SelectedItem", DefaultValueExpression = "new(42)")]

// Also supports the default constructor:
[AttachedDependencyProperty<Data, TreeView>("SelectedItem", DefaultValueExpression = "new()")]

Event Binding

The generator automatically manages properties tied to UI events:

[AttachedDependencyProperty<object, Grid>("BindEventProperty", BindEvent = nameof(Grid.MouseWheel), DefaultValueExpression = "new()")]
public static partial class GridExtensions
{
    private static void OnBindEventPropertyChanged_MouseWheel(object? sender, System.Windows.Input.MouseWheelEventArgs args)
    {
        // Handle the mouse wheel event
    }
}

When the property value changes, it automatically unsubscribes the old value and subscribes the new value to sender.MouseWheel += OnBindEventPropertyChanged_MouseWheel;.

XML Documentation

The easiest way to generate XML documentation is via the Description property:

[DependencyProperty<bool>("IsSpinning", Description = "Indicates whether the element is spinning.")]

This adds the [Description] attribute and embeds the text directly into the generated XML docs. For raw XML, use the XmlDocumentation or PropertyXmlDocumentation properties.

<details> <summary><b>View Generated XML Documentation Code</b></summary>

/// <summary>
/// Identifies the <see cref="IsSpinning"/> dependency property.<br/>
/// Default value: default(bool)
/// </summary>
public static readonly global::System.Windows.DependencyProperty IsSpinningProperty =
    global::System.Windows.DependencyProperty.Register(...);

/// <summary>
/// Indicates whether the element is spinning.<br/>
/// Default value: default(bool)
/// </summary>
[global::System.ComponentModel.Description("Indicates whether the element is spinning.")]
public bool IsSpinning
{
    get => (bool)GetValue(IsSpinningProperty);
    set => SetValue(IsSpinningProperty, value);
}

</details>

Platform Setup

If automatic platform detection fails (e.g., when targeting multiple platforms or custom builds), you can explicitly set your target in the .csproj:

<PropertyGroup>
  <DefineConstants>$(DefineConstants);HAS_WPF</DefineConstants>
  
  
  
</PropertyGroup>

UWP / WinUI / Uno Metadata Overrides

For UWP, WinUI, and Uno, the generator creates a RegisterPropertyChangedCallbacks() method. You must call this method manually in your control's constructor to properly register the property change callbacks.

Prerequisites

<PropertyGroup>
  <LangVersion>11.0</LangVersion> 
</PropertyGroup>

Architecture & Specifications

For in-depth architectural blueprints, zero-allocation design patterns, complexity models, and framework-specific code generation rules, refer to our official specifications:

• Specification Overview & Index (spec/en/intro.md)
  • 01. Foundation and Domain: DTO structure and supported platforms
  • 02. Pipeline Architecture: Delta extraction & cache equivalence strategies
  • 03. Code Synthesis & Performance Optimization: SourceWriter, callback resolution, & guidelines
  • 04. Mathematical Model: Worst-case time & memory complexity analysis
  • 05. Test Specification: Orthogonal matrix and quality assurance criteria
  • 06. Framework Strategies: Platform-specific API mapping
  • 07. Diagnostics Reference: Causes and solutions for DPG0000-DPG9999

Support & Feedback

• Bug Reports & Issues: GitHub Issues
• Discussions & Ideas: GitHub Discussions