清单 9.2 Test1.exe 带有包含双引号的值

>Test1.exe /name:"Raj""s msg" /msg:"Hello world" /r:True

9.3 从外部文件加载参数

一个程序可能有多个大型、复杂的命令行参数集，并且希望多次运行它们，在这种情况下，您可以将值保存到外部文件并将文件传递给程序。这样可以节省每次运行重新键入命令行参数值的时间和精力。

>Test1.exe @"C:\Sample\CmdLineArgs.txt"

10. 验证

在本节中，我将讨论如何验证每个命令行参数成员值、不同的验证方法等。任何接受命令行参数输入的应用程序都必须确保信息在您指定的一些规则集方面是有效的。例如，您可能需要检查客户的电话号码是否具有正确的位数，或者日期是否在特定范围内。此外，如果验证失败，您可能需要发送一条错误消息，解释错误所在。 

Cinchoo 提供了一个类库，称为验证器，它提供用于验证命令行参数成员的代码。例如，一个验证器检查空字符串，另一个验证器检查字符串是否只包含特定字符集等。在某些情况下，您可能希望定义自己的自定义验证器并使用它们来验证成员值。

有一些特殊的验证器用于组合、聚合其他验证器并将它们分组到一个规则集中。

• ChoAndCompositeValidator - 它将其他验证器分组，此复合验证器中的所有验证器都必须为真才能成功验证。
• ChoOrCompositeValidator - 它将其他验证器分组，复合验证器中至少有一个验证器必须为真才能成功验证。

如果您想避免使用此库功能进行验证并自行控制验证，可以通过两种方式实现

• 回调机制 - OnAfterCommandLineArgLoaded 重写方法可用于放置自定义逻辑以验证命令行参数值。
• 属性设置器机制 - 这是另一个可以对这些成员值进行自定义验证的地方。

10.1 使用验证器

以下过程解释了如何在命令行参数对象成员中使用验证器。有两种方法可以为命令行参数成员使用验证器

• ChoValidatorAttribute - 一个通用验证器属性，用于特定验证器没有相应属性的情况。 
• 验证器特定属性 - 这些是每个验证器的自定义验证器属性。例如，ChoStringValidatorAttribute 是 ChoStringValidator 类的属性。 

Cinchoo 开箱即用支持以下验证器

• ChoValidators - Cinchoo 库本身提供的验证器。您可以在 Cinchoo.Core 命名空间下找到许多此类验证器。例如，ChoNotNullValidator、ChoNotNullOrEmptyValidator 等。
• BCL 配置验证器 - .NET BCL 库提供的验证器。您可以在 System.Configuration 命名空间中找到它们。例如，StringValidator、IntegerValidator 等。
• BCL DataAnnotation 验证器 - .NET BCL 库在 System.ComponentModel.DataAnnotations 命名空间下提供的另一组验证器。

10.1.1 使用 ChoValidatorAttribute

这是为命令行参数成员指定验证规则的一种方法。如果特定验证器没有可用的验证器属性，则此属性可用于解决此问题。此属性将验证器类型作为输入。验证器类型可以是以下派生类之一

• Cinchoo.Core.ChoValidator - Cinchoo 框架库提供了许多验证器供您在应用程序中使用。
• System.Configuration.ConfigurationValidatorBase (System.Configuration.dll) - 这些是 .NET BCL 提供的验证器。

以下是此属性可用的可选属性

• ConstructorArgs - 可选。大多数验证器通过构造函数接受一些强制参数，以对命令行对象成员执行验证。这些参数可以通过此属性指定。它接受 object[] 作为值。这些值是位置构造函数参数。
• ConstructorArgsText - 可选字符串值。构造函数参数可以指定为文本，每个值用 ';' 分隔。
• KeyValuePropertiesText - 可选字符串值。它是一个键值对，用 ';' 字符分隔以设置验证器属性值。例如，“MinValue=1;MaxValue=10”。

清单 10.1 带验证器的命令行参数对象

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get;
        set;
    }
}

在上面的示例中，成员 'XmlFilePath' 指定了 2 个验证。它必须不为空 且 必须包含最少 10 个字符。该示例演示了如何使用 ChoValidatorAttribute 来定义没有相应自定义验证器属性的验证器。请注意，顶层指定的多个验证器默认情况下会组合并作为 AND 条件进行验证。验证顺序不保证按顺序执行。 

'OutputDirectory' 成员用与验证器对应的自定义验证器属性进行修饰。在此处，它用 ChoStringValidatorAttribute 和 ChoContainsCharatersValidatorAttribute 修饰。它在声明验证器时提供了灵活性、简单性和类型安全性。

创建一个控制台应用程序并创建 ChoAppCmdLineParams 对象，如下所示

清单 10.2 Main 方法

class Program
{
    static void Main(string[] args)
    {
        ChoAppCmdLineParams cmdLineParams = new ChoAppCmdLineParams();
        Console.WriteLine(cmdLineParams.ToString());
    }
}

下面列出了程序使用不同参数的测试运行

清单 10.3 Test1.exe 没有参数

>Test1.exe
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `xmlfile` command line argument.

The string must be at least 10 characters long.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

在上述运行中，可执行文件在没有传递任何命令行参数的情况下运行。应用程序正在尝试实例化 ChoAppCmdLineParams 对象。在创建此类对象时，框架会尝试验证成员值。在这种情况下，位置命令行参数 'xmlFilePath' 验证失败。应用程序以异常终止。

清单 10.4 Test1.exe 带有不正确的输出目录值

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"C:\Windows\Systems\Xcpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `o` command line argument.

The value must contains ALL of the 'A' characters.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

在上述测试运行中，可执行文件带参数运行。位置参数 'XmlFilePath' 通过了验证（不为 null AND 包含超过 10 个字符）。但它在验证 'OutputDirectory' 时失败。它不包含字符 'A'。应用程序以异常终止。

清单 10.5 Test1.exe 带有正确的值

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"C:\Windows\Systems\Acpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

-- ConsoleApplication2.ChoAppCmdLineParams1 State --
        XmlFilePath: C:\Windows\Systems\cpanal.xml
        OutputDirectory: C:\Windows\Systems\Acpanal.xml

Press any key to continue . . .

在上述测试运行中，可执行文件带有效参数运行。位置参数 'XmlFilePath' 和 'OutputDirectory' 都通过了验证，没有出现任何错误。

10.1.2 使用自定义验证器属性

上一节我谈到了在命令行参数成员上使用通用验证器属性来定义验证。它为在没有验证器属性的情况下使用验证器铺平了道路。一些验证器附带自定义验证器属性。它简单明了，易于使用且类型安全。在下面的示例中，OutputDirectory 成员定义了 2 个带有其自定义属性的验证器。 

清单 10.6 带验证器的命令行参数对象

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get;
        set;
    }
}

10.2 回调机制

如果您想对成员执行一些复杂的验证，可以使用此机制。只需在命令行类中重写 OnAfterCommandLineArgLoaded 方法，如下所示 

清单 10.6 带自定义验证的命令行参数对象

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams1 : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get;
        set;
    }

    protected override void OnAfterCommandLineArgLoaded(string memberName, object value)
    {
        if (memberName == "OutputDirectory")
        {
            if (!((string)value).StartsWith(@"C:\"))
                throw new ArgumentException("Invalid directory passed.");
        }
        else
            base.OnAfterCommandLineArgLoaded(memberName, value);
    }
}

在上面的示例代码中，展示了如何使用回调机制验证成员。如果 'OutputDirectory' 成员值不是以 'C:\' 开头，则会抛出异常。 

清单 10.7 Test1.exe 带有不正确的输出目录值

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"D:\Windows\Systems\Xcpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `o` command line argument.

Invalid directory passed.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

如果使用上述参数值运行示例，则 'OutputDirectory' 成员的验证将失败并抛出异常 'Invalid directory passed.'。

10.3 属性设置器机制

这是另一种对成员执行复杂验证的方法。它的方法与回调机制完全相同。在这里，可以在属性设置器中对属性命令行成员进行验证。请看下面的示例

清单 10.8 带自定义验证的命令行参数对象

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams1 : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    private string _outputDirectory;

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get { return _outputDirectory; }
        set
        {
            if (!value.StartsWith(@"C:\"))
                throw new ArgumentException("Invalid directory passed.");

            _outputDirectory = value;
        }
    }
}

在上面的示例代码中，展示了如何使用属性设置器机制验证成员。'OutputDirectory' 属性的验证在属性设置器中处理。如果值不是以 'C:\' 开头，则会抛出异常。 

清单 10.9 Test1.exe 带有不正确的输出目录值

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"D:\Windows\Systems\Xcpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `o` command line argument.

Invalid directory passed.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

如果使用上述参数值运行示例，则 'OutputDirectory' 成员的验证将失败并抛出异常 'Invalid directory passed.'。

11. 命令行对象构建器 (分组)

到目前为止，我们已经学习了如何在应用程序中定义和使用单个命令行参数对象。它最适合具有单个功能和参数的应用程序。有些应用程序执行多种功能，并带有自己的参数。例如，您有一个应用程序处理各种输入数据（网络、文件、互联网等）的数据，这些数据需要各自的参数。这意味着需要某种工厂，您可以在其中定义这些上下文。基本上，第一个参数将定义要查找的上下文（网络、文件、互联网等），然后任何后续参数将仅充当该特定上下文的参数。

'NET' dos 命令是此场景的完美示例。如果输入 'net'，将产生以下结果

c:\>net
The syntax of this command is:

NET
    [ ACCOUNTS | COMPUTER | CONFIG | CONTINUE | FILE | GROUP | HELP |
      HELPMSG | LOCALGROUP | PAUSE | SESSION | SHARE | START |
      STATISTICS | STOP | TIME | USE | USER | VIEW ]

c:\>net ACCOUNTS /?
The syntax of this command is:

NET ACCOUNTS
[/FORCELOGOFF:{minutes | NO}] [/MINPWLEN:length]
              [/MAXPWAGE:{days | UNLIMITED}] [/MINPWAGE:days]
              [/UNIQUEPW:number] [/DOMAIN]

11.1 定义命令行参数构建器

首先定义命令行对象构建器，如下所示

清单 11.1 命令行参数构建器对象

[ChoCommandLineArgBuilder]
public class NetCmdBuilder : ChoCommandLineArgBuilder
{
    [ChoCommandLineArgBuilderCommand("START", typeof(STARTCmdLineArgObject), Order = 0)]
    [ChoCommandLineArgBuilderCommand("STOP", typeof(STOPCmdLineArgObject), Order = 1)]
    [ChoCommandLineArgBuilderCommand("COMPUTER", typeof(COMPUTERCmdLineArgObject), Order = -1)]
    public NetCmdBuilder()
    {
    }
}

上面的代码演示了如何定义命令行对象构建器对象。首先，从 ChoCommandLineArgBuilder 类定义一个构建器类（例如 NetCmdBuilder），它表示此对象是一个命令行参数构建器对象。并且它必须用 ChoCommandLineArgBuilderAttribute 修饰才能完成定义。除此之外，我们需要在构建器的默认构造函数中使用 ChoCommandLineArgBuilderCommandAttribute 开始定义命令映射。在上面的示例中，构建器定义了 3 个命令 START、STOP 和 COMPUTER，分别映射到 STARTCmdLineArgObject、STOPCmdLineArgObject 和 COMPUTERCmdLineArgObject。 属性中的 order 描述了命令在用法文本中的显示顺序。

清单 11.2 COMPUTERCmdLineArgObject

public enum Action { ADD, DEL };

[ChoCommandLineArgObject(DoNotShowUsageDetail = true)]
public class COMPUTERCmdLineArgObject : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "\\\\computername", IsRequired = true, Order = 0)]
    public string ComputerName;

    [ChoCommandLineArg("action", IsRequired = true)]
    public Action Action;
}

上面的命令行参数包含两个成员：ComputerName - 位置必填参数和 Action - 必填枚举参数。注意，DoNotShowUsageDetail 为 true 告诉框架不要在用法文本中显示每个成员参数的详细信息。

清单 11.3 STARTCmdLineArgObject

[ChoCommandLineArgObject]
public class STARTCmdLineArgObject : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "service")]
    public string ServiceName;
}

清单 11.4 STOPCmdLineArgObject

[ChoCommandLineArgObject(DoNotShowUsageDetail = true)]
public class STOPCmdLineArgObject : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "service", IsRequired = true)]
    public string ServiceName;
}

清单 11.5 Main 方法

class Program
{
    static void Main(string[] args)
    {
        NetCmdBuilder netCmdBuilder = new NetCmdBuilder();
        Console.WriteLine(netCmdBuilder.CommandLineArgObject.ToString());
    }
}

我们首先创建 netCmdBuilder 对象的新实例。就是这样。框架在幕后完成了大部分工作。参数成功加载后，构建器对象的 CommandLineArgObject 成员将根据作为参数传递给可执行文件的上下文加载匹配的命令对象。

下面列出了程序使用不同参数集及其输出的测试运行。

清单 11.6 net.exe 没有参数

c:\>net

The syntax of this command is:

NET [COMPUTER | START | STOP]

Press any key to continue . . .

c:\>net COMPUTER

Missing '\\computername' argument.

NET COMPUTER \\computername {/ADD | /DEL}
Press any key to continue . . . 

c:\>net COMPUTER \\NYC123453 /DEL

-- CommadLineObjectBuilderSample.COMPUTERCmdLineArgObject State --
        ComputerName: \\NYC123453
        Action: DEL

Press any key to continue . . .

[ChoCommandLineArgBuilder]
public class NetCmdBuilder : ChoCommandLineArgBuilder
{
    [ChoCommandLineArgBuilderCommand("START", typeof(STARTCmdLineArgObject), Order = 0)]
    [ChoCommandLineArgBuilderCommand("STOP", typeof(STOPCmdLineArgObject), Order = 1)]
    [ChoCommandLineArgBuilderCommand("COMPUTER", typeof(COMPUTERCmdLineArgObject), Order = -1)]
    public NetCmdBuilder()
    {
    }
}

[ChoCommandLineArgBuilder]
public class ChoNETCommandLineArgBuilder : ChoCommandLineArgBuilder
{
    [ChoCommandLineArgBuilderCommand("ACCOUNTS", typeof(ChoAppCmdLineParams))]
    public ChoNETCommandLineArgBuilder()
    {
    }

    public override Type GetCommandLineArgObjectType(string command)
    {
        if (command == "COMPUTER")
            return typeof(COMPUTERCmdLineArgObject);
        else
            return base.GetCommandLineArgObjectType(command);
    }
}