HansCnc.Core 0.3.0-preview1

HansCnc.Mvvm

轻量级 WPF MVVM 框架：Roslyn 源生成器 + 对话框服务，基于 CommunityToolkit.Mvvm、Autofac、R3。

开发环境：Git 仓库根目录为 HansCnc.Mvvm/（本目录）。若 IDE 工作区打开的是外层文件夹，请在终端中 cd 到本目录再执行 git / dotnet。详见 CONTRIBUTING.md 与 AGENTS.md。

项目结构

安装

NuGet（应用项目）

<PackageReference Include="HansCnc.Mvvm" Version="0.3.0-preview1" />
<PackageReference Include="HansCnc.Mvvm.WPF" Version="0.3.0-preview1" />

完整版说明（HTML，随发布更新）：docs/DOCUMENTATION.html。全量变更记录：docs/CHANGELOG-HISTORY.md。

HansCnc.Mvvm 已包含 Roslyn 分析器（analyzers/dotnet/roslyn*/cs），无需再引用 HansCnc.Mvvm.SourceGenerators。

WPF 应用还需 UseWPF、Autofac、R3 等（见下方依赖）。从旧版三件套迁移见 MIGRATION.md。

本地仓库开发（示例 / 贡献者）

HansCnc.Mvvm.Samples 引用生成器项目以便调试：

<ProjectReference Include="..\HansCnc.Mvvm.SourceGenerators.Roslyn4120\HansCnc.Mvvm.SourceGenerators.Roslyn4120.csproj"
                  OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
<ProjectReference Include="..\HansCnc.Mvvm\HansCnc.Mvvm.csproj" />
<ProjectReference Include="..\HansCnc.Mvvm.WPF\HansCnc.Mvvm.WPF.csproj" />

消费方应用使用 NuGet 四包（HansCnc.Core、HansCnc.DataCollection、HansCnc.Mvvm、HansCnc.Mvvm.WPF；WPF 应用通常显式引用后两者，DataCollection 可由 HansCnc.Mvvm 传递依赖）。启用实时数据采集时导入 HansCnc.Mvvm.DataCollection.props（来自 HansCnc.DataCollection 包）。仅在修改生成器本身时使用 ProjectReference + OutputItemType="Analyzer"。

集合类型

ObservableDictionary 与 NotifyList 不同，专为 WPF 绑定契约设计。在 UI 线程上修改；SyncRoot 提供线程安全，不替代 Dispatcher。

public ObservableDictionary<string, string> Items { get; } = new();

<ItemsControl ItemsSource="{Binding Items}" />

<TextBlock Text="{Binding Items[TitleKey]}" />

源生成器

[IViewFor<TViewModel>]

为 WPF 视图（partial 类）生成 IViewFor<TViewModel> 实现：

[IViewFor<HomeViewModel>]
public partial class HomeView : UserControl { }

生成内容：ViewModelProperty 依赖属性、ViewModel CLR 属性、BindingRoot 便捷属性。

[EditableModel] / [DirtyPart] / [DirtyCollectionPart]

为可编辑实体（partial + ObservableObject）生成 IEditableModel 脏跟踪成员：DirtyContext、DirtyCount、IsDirty、SetDirty、ClearDirty、RaiseDirtyChanged。嵌套图用 [DirtyPart]（引用）与 [DirtyCollectionPart]（IEnumerable<T>，T 须实现 IEditableModel 或标记 [EditableModel]）。

[EditableModel]
public partial class Article : ObservableObject
{
    [DirtyPart]
    public Author Author { get; set; } = new();

    [DirtyCollectionPart]
    public List<Tag> Tags { get; set; } = [];
}

脏标记由业务代码显式调用 SetDirty（生成器不会挂钩属性 setter）。示例见 HansCnc.Mvvm.Samples/EditableModels/。

设计时绑定

在 XAML 根元素绑定到 ViewModel（运行时由 DialogService 或代码赋值）：

<UserControl ...
    DataContext="{Binding RelativeSource={RelativeSource Mode=Self}, Path=ViewModel}"
    d:DataContext="{d:DesignInstance Type=vm:HomeViewModel, IsDesignTimeCreatable=True}">

示例见 HansCnc.Mvvm.Samples/Views/。

[DialogViewModel<TInput, TResult>]

为对话框 ViewModel（partial 类、无显式基类）注入基类 DialogViewModelBase<TInput, TResult>：

[DialogViewModel<string, string>]
public partial class MyDialogViewModel
{
    public void Confirm()
    {
        ResultContext = MvvmDialogResult.Ok(UserInput);
        Ok();
    }
}

生成器只添加基类声明；属性、OkCommand / CancelCommand、生命周期与 IDialogViewModel 成员均由 DialogViewModelBase 提供。

对话框

注册（Autofac）

var builder = new ContainerBuilder();

builder.UseDialogService();
builder.RegisterDialog<MyDialogViewModel, MyDialogWindow>();

// 约定：FooDialogViewModel → FooDialogWindow（同一程序集）
builder.RegisterDialogsFromAssembly(typeof(MyDialogViewModel).Assembly);

使用

var result = dialogService.ShowDialog<MyDialogViewModel, string, string>("输入值");
if (result.Result)
    Console.WriteLine(result.ResultValue);

DialogService 通过 IViewFor<TViewModel>.ViewModel 绑定 ViewModel（不设置 Window.DataContext）。对话框窗口须实现 IViewFor<TViewModel>（推荐 [IViewFor<T>] + partial）。

窗口行为约定

DialogViewModelBase 提供 Input、ResultContext、Initialize、Ok() / Cancel() 及上述生命周期虚方法。确认前设置 ResultContext，再调用 Ok()；取消调用 Cancel()。

视图激活（R3）

[IViewFor<HomeViewModel>]
public partial class HomeView : UserControl
{
    public HomeView()
    {
        this.WhenActivated(disposables =>
        {
            // 视图激活时的订阅
        });
    }
}

当 ViewModel 实现 IActivatableViewModel 时，WhenActivated 会在首次激活/全部停用时调用 HandleActivation / HandleDeactivation。

UI 线程（MainThreadHelper）

MainThreadHelper.Invoke(() => { /* UI 线程同步 */ });
await MainThreadHelper.InvokeAsync(() => { /* UI 线程异步 */ });
MainThreadHelper.BeginInvoke(() => { /* 投递到队列，避免重入 */ });
MainThreadHelper.DoEvents(); // 长同步操作中偶尔泵送消息
MainThreadHelper.VerifyAccess(); // 断言当前在 UI 线程

属性 UiDispatcher 暴露缓存的 WPF 调度器（避免与 System.Windows.Threading.Dispatcher 类型同名冲突）。

R3 流与 UI 线程

应用启动时配置 R3 的 WPF 调度（Samples 使用 R3Extensions.WPF）：

// App.xaml.cs
WpfProviderInitializer.SetDefaultObservableSystem(
    ex => Log.Error(ex, ex.Message),
    DispatcherPriority.Background,
    Dispatcher);

命令式 UI 用 MainThreadHelper；Observable 流 用 ObserveOnUi / SubscribeOnUi：

this.WhenActivated(d =>
{
    ViewModel!.WhenAnyValue(vm => vm.Counter)
        .ObserveOnUi()
        .Subscribe(c => { /* UI 线程回调 */ })
        .DisposeWith(d);
});

// 或把流绑到 ViewModel 属性（无 OAPH）：
ViewModel!.WhenAnyValue(vm => vm.Counter)
    .SubscribeOnUi(c => viewModel.CounterDescription = $"已计 {c} 次");

WPF 控件事件 → Observable 请使用 MvvmAIO.R3.SourceGenerators（FromEvents / FromRoutedEvents）。属性观察见 WhenAnyMixin；ReactiveUI 迁移见 docs/MIGRATION-REACTIVEUI.md。

文档

构建与测试

.\build.ps1

dotnet build HansCnc.Mvvm.slnx -c Release
dotnet test HansCnc.Mvvm.slnx -c Release --no-build

WPF 与集成测试需在 Windows 上运行。升级 MvvmAIO.R3.SourceGenerators 见 docs/DEPENDENCIES.md。

稳定 API（预览期）

在 0.1.0 之前仍可能调整，但以下面为对外承诺的主契约：IViewFor / [IViewFor]、[DialogViewModel]、DialogViewModelBase、IDialogService、DialogService、WhenActivated、MainThreadHelper、MvvmDialogResult<T>、诊断 HMVVM0001–0005。详见 CONTRIBUTING.md 与 docs/MIGRATION.md。

核心特性

• IViewFor 源生成器 — 消除 DependencyProperty 样板代码
• DialogViewModel 源生成器 — 属性标记 + DialogViewModelBase 分工
• DialogService — 类型安全的模态/非模态对话框
• WhenActivated — 基于 R3 的视图生命周期
• MainThreadHelper — UI 线程封送与 DoEvents
• 多 Roslyn 版本 — 4.0.1 / 4.3.1 / 4.12.0 / 5.0.0

依赖

• CommunityToolkit.Mvvm — MVVM 基元
• Autofac — IoC 容器
• R3 — 响应式扩展
• R3Extensions.WPF — WPF 调度（HansCnc.Mvvm.WPF 全 TFM 引用，最低 net472；应用启动建议 WpfProviderInitializer）
• MvvmAIO.R3.SourceGenerators — WPF 事件源生成（HansCnc.Mvvm.WPF 内部使用；应用侧同样可用）
• Serilog — 日志（HansCnc.Mvvm.WPF 可选）

许可证

MIT