Cake.ArgumentBinder 3.0.0

Cake.ArgumentBinder

将传入 Cake 的参数绑定到配置类的方法。

关于

此 Cake（一个 C# 构建系统）的附加组件，允许您将 Cake 传入的参数绑定到 C# 类，而不必手动进行。

说实话，对于 Cake 的大多数用户来说，此附加组件可能有点多余（即使是这个项目的 cakefile 也没有使用它）。它原本是为复杂、灵活的构建环境设计的，其中有多个任务和从命令行传入的多个配置。

软件包

工作原理

假设在调用 Cake 中定义的目标时，目标需要从用户处获取几个参数才能执行。在这个例子中，它是在删除目录中的文件。一个选项是只需使用 Arguments 函数解析这些参数。

string path = Argument( "path", string.Empty );
string pattern = Argument( "pattern", string.Empty );
int filesToKeep = Argument<int>( "num_to_keep", 0 );
bool dryRun = Argument<bool>( "dry_run", false );

这很好，但是现在可能需要进行验证以确保传入的参数不是空字符串，并且要保留的文件数量不是负数。

别忘了在描述中添加每个参数的作用、哪些参数是必需的等内容！这会变得非常无聊，尤其是在环境中有多个任务的情况下。如果我们可以将这些参数绑定到我们可以无任何问题使用的类中，那会不错吗？

使用此附加组件，现在您可以这样做，借助属性的力量。现在，您不再需要手动获取参数，只需创建一个配置类并将相应的属性标记为正确的属性。

public class DeleteHelpersConfig
{
    // ---------------- Properties ----------------

    /// <summary>
    /// The directory to delete things from.
    /// </summary>
    [StringArgument(
        "path",
        Description = "The path to delete from.",
        Required = true,
        ArgumentSource = ArgumentSource.CommandLineThenEnvironmentVariable
    )]
    public string Directory { get; set; }

    /// <summary>
    /// The number of files or directories 
    /// to keep that match the given pattern.
    /// Defaulted to 0.
    /// Can not be negative.
    /// </summary>
    [IntegerArgument(
        "num_to_keep",
        Description = "The number of the most recent files/directories to keep that match the pattern.",
        DefaultValue = 0,
        Min = 0,
        Max = 255,
        ArgumentSource = ArgumentSource.CommandLineThenEnvironmentVariable
    )]
    public int NumberOfFilesToKeep { get; set; }

    /// <summary>
    /// The glob of the deletion pattern to use.
    /// </summary>
    [StringArgument(
        "pattern",
        Description = "The glob pattern to delete files/directories from.",
        DefaultValue = "*",
        ArgumentSource = ArgumentSource.CommandLineThenEnvironmentVariable
    )]
    public string DeletionPattern { get; set; }

    [BooleanArgument(
        "dry_run",
        Description = "Set to 'true' to not delete any files, this will simply print what files will be deleted.",
        DefaultValue = false,
        ArgumentSource = ArgumentSource.CommandLineThenEnvironmentVariable
    )]
    public bool DryRun { get; set; }
}

现在在您的 Task 中，您不必解析和验证多个参数，ArgumentBinder 会为您处理所有这些。您只需在任务中这样做即可

Task( "delete_files" )
.Does(
    ( context ) =>
    {
        DeleteHelpersConfig config = CreateFromArguments<DeleteHelpersConfig>();
        DeleteHelpers.DeleteFiles( context, config );
    }
)
.DescriptionFromArguments<DeleteHelpersConfig>( "Deletes specified files." );

现在，如果您在命令行中输入 cake --showdescription，您将看到任务和所有参数的打印输出。

Task                          Description
================================================================================
delete_files                  Deletes specified files.
- Arguments:
         --path
                The path to delete from.
                Type: String
                This argument is Required.

         --num_to_keep
                The number of the most recent files/directories to keep that match the pattern.
                Type: Integer
                Default Value: 0
                Minimum Value: 0
                Maximum Value: 255

         --pattern
                The glob pattern to delete files/directories from.
                Type: String
                Defaulted to: *

         --dry_run
                Set to 'true' to not delete any files, this will simply print what files will be deleted.
                Type: Boolean
                Default Value: False

如果您没有指定必要的参数，您将收到一个有用的错误信息。

cake --target=delete_files

========================================
delete_files
========================================
An error occurred when executing task 'delete_files'.
Error: One or more errors occurred.
        Argument 'path' is required, but was never specified.

如果您指定了一个无效的参数，您也会收到一个有用的错误信息（例如，低于保留文件的最小值）。

cake --target=delete_files --path="." --dry_run=true --num_to_keep=-1

========================================
delete_files
========================================
An error occurred when executing task 'delete_files'.
Error: One or more errors occurred.
        Value specified in argument 'num_to_keep' is less than the minimum value of '0'.

您也可以通过设置“ArgumentSource”属性来指定参数的来源。有四种选项。

• CommandLine（默认）- 值来自命令行参数。
• EnvironmentVariable - 值来自环境变量。
• CommandLineThenEnvironmentVariable - 值首先来自命令行，但如果未指定相应的命令行参数，则回退到环境变量。
• EnvironmentVariableThenCommandLine - 值首先来自环境变量，但如果未指定该名称的环境变量，则回退到命令行。

最佳实践

• 请将“Configuration”类与其他执行任何操作的课程或函数分开。这不仅有助于问题分离，而且与Cake的行为一致。

故障排除

• 确保在将参数绑定到课程中，您可能需要包含使用语句 using Cake.ArgumentBinder;，否则编译器无法找到属性，并产生大量错误。

讨论

有关问题和讨论想法以及功能请求，请使用 GitHub上的Cake GitHub存储库中的讨论，在 扩展Q&A类别下。

版本

Cake.ArgumentBinder的版本不是语义版本化。相反，主要版本（x.y.z中的x）是库编译所针对的Cake版本。例如，如果Cake.ArgumentBinder依赖于Cake版本2.0.0，则Cake.ArgumentBinder的版本将是2.y.z。次要版本（x.y.z中的y）将在添加了新功能时递增。修订版（x.y.z中的z）将在发生错误修复时递增。我们将尽可能减少破坏向后兼容性的情况，并且仅在发布新版本的Cake时才这样做。

许可证

为了与Cake本身保持一致，Cake.ArgumentBinder在MIT许可证下发布。这包括示例。