重大升级

Author: walterlv

ApiChanges.3.x-4.0.md

@@ -0,0 +1,80 @@
+# 重大更新
+
+## 3.x -> 4.0
+
+dotnetCampus.CommandLine 4.0版本带来了全面的架构升级和功能增强，使命令行参数解析更加高效、灵活且易于使用。
+
+### 主要更新内容
+
+#### 1. 全面采用源代码生成器
+
+- 完全使用源生成器技术，替代以前的手写解析器（`XxxParser`）和反射解析器（`RuntimeParser`）
+- 大幅提升解析性能，处理一次命令行解析只需约 5000ns（0.005ms）
+- 充分支持 AOT 编译，更适合现代 .NET 应用场景
+- 性能测试显示明显优于其他主流命令行解析库
+
+#### 2. 全面增强的命令行风格支持
+
+- 从原来支持 Linux/GNU、CMD、PowerShell 三种风格的有限子集，升级为全面支持五种完整命令行风格：
+  - `CommandLineStyle.Flexible`（默认）：智能识别多种风格
+  - `CommandLineStyle.GNU`：符合 GNU 规范的风格
+  - `CommandLineStyle.POSIX`：符合 POSIX 规范的风格
+  - `CommandLineStyle.DotNet`：.NET CLI 风格
+  - `CommandLineStyle.PowerShell`：PowerShell 风格
+- 全面支持各种命令行选项格式：
+  - 长选项：`--option value`、`--option=value`、`--option:value`
+  - 短选项：`-o value`、`-o=value`、`-o:value` 
+  - Windows风格：`/option value`、`/option:value`
+  - 布尔选项：`--flag`（无值时自动设为true）、`--flag:true/false`
+  - URL协议风格：`protocol://command/subcommand?param1=value&param2=value`
+
+#### 3. 增强的类型系统支持
+
+- 支持 C# 8.0+ 的 `init` 和 C# 11.0 的 `required` 关键字，完美支持不可变对象模式
+- 全面支持更多复杂数据类型：
+  - 集合类型：数组、列表、只读集合、不可变集合
+  - 字典类型：支持多种传入方式和分隔符
+  - 枚举类型：支持枚举名称和数值
+- 增强类型转换能力，提供更友好的类型错误提示
+
+#### 4. 改进的命令处理器模式
+
+- `AddHandler<T>` 现在支持实现 `ICommandHandler` 接口的类型，可以在类型内部编写处理逻辑
+- 保留了通过委托方式传入处理逻辑的经典用法
+- 提供更强大的异步命令处理支持
+
+### 破坏性变更和升级指南
+
+1. **命名空间变更**：`OptionAttribute`、`ValueAttribute`、`VerbAttribute` 的命名空间发生了变化。升级库后，您可能需要借助IDE来修正相关引用。
+
+2. **参数解析选项变更**：`CommandLine.Parse(args, xxx)` 的第二个参数已从简单的URL scheme字符串升级为完整的 `CommandLineParsingOptions` 对象：
+   ```csharp
+   // 旧版本
+   var commandLine = CommandLine.Parse(args, "myapp");
+   
+   // 新版本
+   var commandLine = CommandLine.Parse(args, new CommandLineParsingOptions { SchemeNames = ["myapp"] });
+   // 或者使用预定义样式
+   var commandLine = CommandLine.Parse(args, CommandLineParsingOptions.DotNet);
+   ```
+
+3. **命名约定变更**：选项命名规则从 `PascalCase` 改为推荐使用 `kebab-case`：
+   ```csharp
+   // 旧版本（依然支持，但不再推荐）
+   [Option("OutputFile")]
+   
+   // 新版本（推荐）
+   [Option("output-file")]
+   ```
+   
+4. **标准处理器移除**：删除了 `AddStandardHandlers` 方法（用于自动处理 `--help` 和 `--version`）。这个功能在未来版本可能会以新形式回归，如有需要请暂时自行实现。
+
+5. **过滤器机制移除**：删除了很少使用的 `CommandLineFilter` 机制，该机制主要为 `AddStandardHandlers` 提供支持。
+
+### 保留的功能
+
+1. **多种命令行风格解析**：保留并增强了对多种命令行参数风格的支持
+2. **URL协议支持**：完整保留并改进了对URL协议格式命令行的解析
+3. **位置参数支持**：保留了对位置参数的支持，并增强了位置参数的处理能力
+4. **谓词（命令）支持**：保留并增强了对命令谓词的支持（如 `git commit`、`git push` 等形式）
+5. **简单流畅的API**：保持了简洁易用的API设计风格