0 Fork 0

Files

T

2026-10-27 19:01:56 +08:00

4.6 KiB

Raw Blame History

name, description

name	description
max-common	在 .NET 项目中接入和使用 MAX.Common，复用其命令、属性通知、集合视图、数值与文件工具、枚举和事件功能。适用于明确使用 MAX.Common 或项目已引用该库的开发任务；WPF 控件和附加行为由 max-common-wpf 处理。

MAX.Common 功能使用

帮助消费项目复用 MAX.Common 的真实能力，避免重复实现已有工具。此 Skill 是使用指南，不包含库二进制，也不要求访问原开发仓库。

接入与版本

先检查消费项目的 .csproj、Directory.Packages.props、NuGet 配置和已有 using，保留其依赖管理方式。
本参考基于 2026-10-27 的源码快照：包 MAX.Common 1.4.17，目标为 netstandard2.0;netstandard2.1。这是快照版本，不代表最新版本。优先沿用项目已安装的兼容版本；需要新增时使用可用源中的确定版本。
普通项目通过 PackageReference Include="MAX.Common" Version="1.4.17" 接入；集中包管理项目将版本放到 PackageVersion。源码工程采用 C# 12，不代表所有调用项目都必须使用 C# 12。
PolySharp 是库构建依赖（PrivateAssets=all），不要仅为调用库强制添加它。没有必要为使用本库引入 MAX.Core、Prism 或其他应用框架。

按需求选择功能

先阅读功能索引中与任务对应的部分。需要确定命名空间、构造参数和方法名称时，搜索常用 API 声明的文件名或类型名；这是选定功能的声明摘录，不是全部 API，也不包含完整实现语义。

引用的包版本与快照不同时，以本地已安装包 XML 文档、反射结果、源码或编译器为准。没有源码时不假设原仓库存在，更不编造未收录的方法。

已确认的使用约束

MethodCommand<T> 和 AsyncMethodCommand<T> 只接受引用类型或可空值类型，例如 int?；int 会在构造时抛出异常。传入的实际 CommandParameter 仍必须能转换为 T。
命令状态变化后调用 RaiseCanExecuteChanged()；库不会自动观察业务属性。同步命令的 Execute 不检查 CanExecute，程序直接执行时自行判断。
AsyncMethodCommand 使用 async void Execute，执行期间拒绝重复执行，通过 finally 恢复状态，但不吞掉业务异常。需要呈现错误时在异步委托中捕获并处理；它不是可 await 的 ExecuteAsync API，也不是跨线程互斥锁。
BindModelBase 使用 SetProperty(ref field, value, ...)；BindableBaseEx 同时提供属性包 GetValue/SetValue 和字段方式。两者构造函数都会调用虚方法 OnInitialized()，不要在该回调中依赖派生构造函数才完成的初始化。
BindModelBase 先执行 onChanged 再通知属性变化，BindableBaseEx 的字段设置先通知再调用 changedCallback。涉及通知顺序时不要将二者视为完全等价。
AsyncEvent<TEventArgs> 通过可空字段 += 首次创建，构造函数私有；InvokeAsync 按注册顺序逐个 await，异常会中止后续回调。首次并发订阅存在竞争，不能当作线程安全事件总线。
RunLimiter 限制实例生命周期内的尝试次数，不是时间窗口节流，也不限制同时运行数；动作抛异常也已消耗计数。
PathValidator.IsFolderPathValidAndSafe(path, allowRelativePath) 检查路径格式，不保证存在、可写或位于允许的根目录；路径范围约束需要调用方另外实现。
SerializationHelper.TryGetValue 面向 SerializationInfo，失败返回默认值，不是 JSON 序列化工具。MD5Helper、Base64 和 URI 编码工具的名称不代表它们提供密码加密。

最小用法

using MAX.Common.Commands;
using MAX.Common.Models;

public sealed class EditorModel : BindModelBase
{
    private string name = string.Empty;
    public MethodCommand ClearCommand { get; }

    public EditorModel()
    {
        ClearCommand = new MethodCommand(() => Name = string.Empty,
            () => Name.Length > 0);
    }

    public string Name
    {
        get => name;
        set
        {
            if (SetProperty(ref name, value))
                ClearCommand.RaiseCanExecuteChanged();
        }
    }
}

验证与交付

按消费项目实际 TFM 构建。对使用到的行为验证关键边界，例如命令空参数与异常恢复、集合空源与索引、文件路径无效输入。只调用本库时无需构建整个原始解决方案。交付时说明引用版本、变更文件与验证结果；未执行的验证明确标注，可按需继续代码审查。

4.6 KiB Raw Blame History Unescape Escape