Files
Store.Management/.agents/skills/max-common/SKILL.md
T
2026-10-27 19:01:56 +08:00

67 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: max-common
description: 在 .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 或其他应用框架。
## 按需求选择功能
先阅读 [功能索引](references/features.md) 中与任务对应的部分。需要确定命名空间、构造参数和方法名称时,搜索 [常用 API 声明](references/api.md) 的文件名或类型名;这是选定功能的声明摘录,不是全部 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 编码工具的名称不代表它们提供密码加密。
## 最小用法
```csharp
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 构建。对使用到的行为验证关键边界,例如命令空参数与异常恢复、集合空源与索引、文件路径无效输入。只调用本库时无需构建整个原始解决方案。交付时说明引用版本、变更文件与验证结果;未执行的验证明确标注,可按需继续代码审查。