语言运行时标准库JIT编译编译器【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址https://gitcode.com/GitHub_Trending/runtime6/runtime点击查看免费下载本文以 dotnet/runtime 仓库中的Microsoft.Extensions.Configuration.CommandLine包为对象系统讲解如何通过IConfigurationBuilder.AddCommandLine扩展方法从程序命令行参数中读取配置。读者将掌握五种命令行参数格式的写法、短开关short switch与别名alias映射的配置方法、重复键与非法参数的边界行为并深入理解底层CommandLineConfigurationProvider.Load的解析原理能够直接在控制台应用、ASP.NET Core 宿主程序中使用命令行配置提供器。一、包简介与核心 APIMicrosoft.Extensions.Configuration.CommandLine是 .NET 通用配置体系Microsoft.Extensions.Configuration的命令行配置提供器实现。它的作用非常纯粹把应用程序启动时传入的命令行参数args解析为一组配置键值对并入配置系统后续可通过IConfiguration统一读取。该包的核心 API 只有三个类定义于 ref/Microsoft.Extensions.Configuration.CommandLine.cs类型职责CommandLineConfigurationExtensions位于Microsoft.Extensions.Configuration命名空间提供AddCommandLine扩展方法注册提供器CommandLineConfigurationSource实现IConfigurationSource承载参数与开关映射配置CommandLineConfigurationProvider继承ConfigurationProvider真正执行参数解析最常用的入口是AddCommandLine扩展方法它有三个重载public static IConfigurationBuilder AddCommandLine(this IConfigurationBuilder configurationBuilder, string[] args); public static IConfigurationBuilder AddCommandLine(this IConfigurationBuilder configurationBuilder, string[] args, IDictionarystring, string? switchMappings); public static IConfigurationBuilder AddCommandLine(this IConfigurationBuilder builder, ActionCommandLineConfigurationSource? configureSource);三个重载最终都会构造一个CommandLineConfigurationSource并追加到 builder 上见 CommandLineConfigurationExtensions.cs前两个是快捷方式第三个configureSource重载便于在 DI 场景下以委托方式配置源。二、快速上手第一个命令行配置示例原包说明文档PACKAGE.md给出了最简示例。创建一个控制台应用代码如下using System; using Microsoft.Extensions.Configuration; class Program { static void Main(string[] args) { // Build a configuration object from command line IConfiguration config new ConfigurationBuilder() .AddCommandLine(args) .Build(); // Read configuration values Console.WriteLine($InputPath: {config[InputPath]}); Console.WriteLine($OutputPath: {config[OutputPath]}); } }使用如下命令运行dotnet run --InputPath c:\fizz --OutputPath c:\buzz程序将输出InputPath: c:\fizz OutputPath: c:\buzz需要注意一个细节dotnet run会把--之后的参数原样传给应用部分参数需要转义而args数组中的元素进入提供器后--InputPath这类前缀会被剥离c:\fizz被作为值保存。三、五种基础参数格式与解析规则根据 CommandLineConfigurationExtensions.cs 中AddCommandLine的文档注释命令行参数存在五种等价的基础写法它们可以混用key1value1 --key2value2 /key3value3 --key4 value4 /key5 value5写法示例说明无前缀 等号Key1Value1等号左侧作为键右侧作为值双横线 等号--Key2Value2--前缀最常用等号分隔正斜杠 等号/Key3Value3/是--的等价替代双横线 空格--Key4 Value4下一个参数整体作为值正斜杠 空格/Key5 Value5同上用/替代--这一规则在 CommandLineConfigurationProvider.cs 的Load()方法中有精确实现以--开头时keyStartIndex 2以-开头时keyStartIndex 1以/开头时源码会先做一步转换currentArg $--{currentArg.Substring(1)}即/SomeSwitch等价于--SomeSwitch源码注释明确指出 /SomeSwitchis equivalent to--SomeSwitchwhen interpreting switch mappings随后keyStartIndex 2若当前参数既不包含也没有任何前缀keyStartIndex 0则该参数被判定为非法格式并直接忽略continue找到后之前的部分为键、之后的部分为值键与值之间以空格分隔时则消耗下一个参数作为值——如果下一个参数不存在该键被忽略源码注释 ignore missing values。大小写不敏感Load()内部以StringComparer.OrdinalIgnoreCase构造数据字典CommandLineConfigurationProvider.cs#L43因此--InputPath、--inputpath、--INPUTPATH读取到的是同一个配置项。重复键后者覆盖前者源码在解析循环的末尾执行data[key] value;并注释 Override value when key is duplicated. So we always have the last argument win.——重复的键总是以最后一个参数为准。测试 CommandLineTest.cs 验证了这一点/Key1Value1之后紧跟--Key1Value2最终读取到Value2。四、switchMappings短开关与别名键基础格式要求键名即配置键名这限制了命令行书写的灵活性。为此AddCommandLine(args, switchMappings)提供了**开关映射switch mappings**机制允许把短键和别名键映射到完整的配置键上。4.1 短开关short switch单横线-短键以单横线开头例如-k1它不能直接作为配置键访问必须通过 switchMappings 映射到完整键名。映射字典的键必须以-开头值是不带前缀的完整配置键名var switchMappings new Dictionarystring, string(StringComparer.OrdinalIgnoreCase) { { -k1, key1 }, { -k2, key2 }, }; var builder new ConfigurationBuilder(); builder.AddCommandLine(args, switchMappings); var config builder.Build(); Console.WriteLine($Key1: {config[Key1]}); Console.WriteLine($Key2: {config[Key2]});运行dotnet run -k1value1 -k2 value2短开关支持等号和空格两种分隔格式-k1value1 -k2 value2。4.2 别名键alias双横线--或斜杠/别名键以--开头映射到完整键名可用于替代正常键名当命令行中使用/前缀时别名同样生效但无前缀的等号格式不参与别名解析。映射示例var switchMappings new Dictionarystring, string() { { --alt3, key3 }, { --alt4, key4 }, { --alt5, key5 }, { --alt6, key6 }, }; var builder new ConfigurationBuilder(); builder.AddCommandLine(args, switchMappings);运行dotnet run --alt3value3 /alt4value4 --alt5 value5 /alt6 value6别名参数只有四种格式--alt3value3、/alt4value4、--alt5 value5、/alt6 value6斜杠写法在源码中先被转换为--前缀再查映射表。4.3 映射校验不是随便写的字典GetValidatedSwitchMappingsCopyCommandLineConfigurationProvider.cs在构造提供器时对映射做两层校验键必须以-开头否则抛出ArgumentException错误消息为 The switch mappings contain an invalid switch {0}.资源定义见 Strings.resx 的Error_InvalidSwitchMapping键在忽略大小写后不得重复因为配置系统的键全部大小写不敏感传入的映射如果含有--KEY1与--key1这类重复将抛出ArgumentExceptionKeys in switch mappings are case-insensitive. A duplicated key {0} was found.Error_DuplicatedKeyInSwitchMappings。对应测试见 CommandLineTest.cs。4.4 未定义短开关的两种不同结局这是最容易踩坑的边界行为且取决于是否有带等号如-K1Value1而映射中没有-K1Load()会抛出FormatException消息为 The short switch {0} is not defined in the switch mappings.Error_ShortSwitchNotDefined不带等号空格分隔-K1 Value1而映射中没有-K1则静默忽略源码else if (keyStartIndex 1) continue;测试 CommandLineTest.cs 验证了忽略行为。五、三层对象模型与源码实现原理该包的设计遵循 .NET 配置体系的标准三段式IConfigurationBuilder→IConfigurationSource→IConfigurationProvider。5.1 CommandLineConfigurationSource配置源CommandLineConfigurationSource.cs 实现IConfigurationSource仅暴露两个属性public IDictionarystring, string? SwitchMappings { get; set; } public IEnumerablestring Args { get; set; } Array.Emptystring();其Build(IConfigurationBuilder builder)直接return new CommandLineConfigurationProvider(Args, SwitchMappings);——源是静态配置Provider 才是运行时解析器。5.2 CommandLineConfigurationProvider解析核心CommandLineConfigurationProvider继承自ConfigurationProvider基类把解析结果写入继承来的Data字典。构造器要求args非空ArgumentNullException.ThrowIfNull(args)测试ThrowExceptionWhenNullIsPassedToConstructorAsArgs验证。Load()是全部逻辑所在完整解析流程可用如下伪代码概括foreach arg in args: if arg 以 -- 开头: keyStartIndex 2 elif arg 以 - 开头: keyStartIndex 1 elif arg 以 / 开头: arg -- 去掉前导/的部分; keyStartIndex 2 else: keyStartIndex 0 separator arg 中第一个 的位置 if 没有 : if keyStartIndex 0: 忽略无前缀无等号非法 if 命中 switchMappings: key 映射值 elif keyStartIndex 1: 忽略未定义的短开关 else: key 去掉前缀后的参数名 若无下一个参数: 忽略缺值 value 下一个参数 else: 键段 之前的部分 if 键段命中 switchMappings: key 映射值 elif keyStartIndex 1: 抛 FormatException未定义短开关 else: key 去掉前缀后的键段 value 之后的部分 data[key] value // 重复键后者覆盖5.3 与泛型宿主Hosting的集成除了手动new ConfigurationBuilder()命令行配置提供器还被 .NET 泛型主机的默认构建流程自动接入在 HostingHostBuilderExtensions.cs 中ConfigureHostConfiguration默认执行configBuilder.AddCommandLine(args)因此使用Host.CreateDefaultBuilder(args)的应用开箱即用地就能通过命令行覆盖配置测试示例见 TestApp/Program.cs。5.4 与其他配置提供器的叠加顺序命令行配置通常叠加在 appsettings.json 等文件配置之后使其具备最高优先级后添加的提供器覆盖先添加的同名键。典型顺序为appsettings.json→appsettings.{Environment}.json→ 环境变量 → 命令行这也是Host.CreateDefaultBuilder的默认顺序。六、边界行为速查表输入场景行为依据无前缀且无等号的参数如foo忽略Load()中keyStartIndex 0分支键缺值如/Key2是最后一个参数忽略该键ignore missing values 分支重复键最后一个参数胜出data[key] value 测试OverrideValueWhenKeyIsDuplicated未定义短开关 等号-K1抛FormatExceptionError_ShortSwitchNotDefined未定义短开关 空格-K 1静默忽略keyStartIndex 1分支映射键不以-开头抛ArgumentExceptionError_InvalidSwitchMapping映射键大小写不敏感重复抛ArgumentExceptionError_DuplicatedKeyInSwitchMappings构造参数args为 null抛ArgumentNullException测试ThrowExceptionWhenNullIsPassedToConstructorAsArgs空值支持不支持SupportNullValues falseConfigurationProviderCommandLineTest.cs其中最后一项值得注意与 JSON 等配置源不同命令行参数本身没有空值概念ConfigurationProviderCommandLineTest通过覆写SupportNullValues为false关闭了基类的空值测试分支。七、测试体系与验证方式仓库为该包配备了完整的单元测试是理解行为边界的最佳教材CommandLineTest.cs覆盖五格式混用、短开关/别名映射、重复键覆盖、缺值忽略、未识别参数忽略、映射校验异常、null 参数等 9 个用例ConfigurationProviderCommandLineTest.cs继承ConfigurationProviderTestBase通过把TestSection树递归转成--Section:KeyValue形式的参数验证分层键如Section:Key用冒号:表示层级的解析测试中的SectionToArgs展示了分层配置键与命令行格式的对应关系。八、包部署与目标框架根据 csproj该包目标框架覆盖.NETCoreApp当前/上一版/最低版本、netstandard2.0与 .NET Framework 最低版本并引用Microsoft.Extensions.Configuration及Microsoft.Extensions.Configuration.Abstractions。按 README.md 的说明它已包含在 ASP.NET Core 共享框架中同时也以 out-of-bandOOB包形式发布可被项目直接引用——这意味着绝大多数 .NET 项目无需额外安装即可使用AddCommandLine独立打包分发时只需添加 NuGet 包引用。九、小结与进阶阅读命令行配置提供器是 .NET 统一配置体系中成本最低、见效最快的一环无需文件、无需环境变量仅凭args就能在部署时覆盖任意配置项。掌握本文的五个基础格式、短开关/别名映射与边界行为就足以应对从控制台工具到微服务启动参数的绝大多数场景。想继续深入可以在本仓库中阅读包文档PACKAGE.md 与 README.md核心实现CommandLineConfigurationProvider.cs、CommandLineConfigurationSource.cs、CommandLineConfigurationExtensions.cs测试用例CommandLineTest.cs、ConfigurationProviderCommandLineTest.cs宿主集成HostingHostBuilderExtensions.cs此外配置系统的通用约定如键的冒号分层、大小写不敏感、Provider 叠加顺序遵循仓库根目录 src/libraries 下Microsoft.Extensions.Configuration系列包的统一设计可一并研读。赞分享语言运行时标准库JIT编译编译器【免费下载链接】runtime.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.项目地址https://gitcode.com/GitHub_Trending/runtime6/runtime点击查看免费下载相关推荐.NET 命令行配置提供程序Microsoft.Extensions.Configuration.CommandLine完全指南.NET 命令行配置提供程序Microsoft.Extensions.Configuration.CommandLine完全指南 本篇技术指南围绕 .NET语言运行时标准库JIT编译编译器.NET 运行时 User Secrets 配置提供程序Microsoft.Extensions.Configuration.UserSecrets原理与实战.NET 运行时 User Secrets 配置提供程序Microsoft.Extensions.Configuration.UserSecrets原理与实语言运行时标准库JIT编译编译器DiceDB 数据清空指南深入解析 FLUSHDB 命令的实现原理与实战用法DiceDB 数据清空指南深入解析 FLUSHDB 命令的实现原理与实战用法 导读 FLUSHDB 是 DiceDB 中用于清空当前数据库全部键key的核数据库缓存后端上一篇如何5分钟搞定黑苹果EFI配置OpCore-Simplify终极指南下一篇Simple Icons 图标路径优化终极指南从多点到复合路径的简化技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考