67 lines
4.6 KiB
Markdown
67 lines
4.6 KiB
Markdown
---
|
||
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 构建。对使用到的行为验证关键边界,例如命令空参数与异常恢复、集合空源与索引、文件路径无效输入。只调用本库时无需构建整个原始解决方案。交付时说明引用版本、变更文件与验证结果;未执行的验证明确标注,可按需继续代码审查。
|