CommandDotNet Documentation

CommandDotNet v3 introduces several advanced capabilities:

• Argument Handling:
  • Response files: Support for providing arguments via files.
  • Password type: A specialized type to prevent accidental logging and hide values during prompting.
  • Piped input: Mapping piped input to operand lists.
  • Arity: Calculated for arguments and updatable via middleware.
  • Lists: Parameters can be arrays or enumerables streamed from files or piped input.
• User Interaction:
  • Prompting: A tool for interactive input that honors Password types and Ctrl+C cancellation. Note: List values are now delimited by line instead of comma; enter an empty line to submit.
• Extensibility & Testing:
  • Middleware pipeline: The core architecture for all framework operations.
  • Parameter resolvers: For custom argument resolution.
  • Test tools: For end-to-end testing and middleware testing.
  • HelpTextProvider: Can be overridden for targeted help section changes.
• Integration:
  • SimpleInjector support.
  • IoC runInScope: Enables isolated instances per run.
  • IArgumentModel: Can be resolved from containers with support for AppSettings defaults.

When creating middleware that requires additional parameters (like connection strings or flags), use a private Config class to store these parameters in the service container. This allows the middleware delegate to access the configuration via the CommandContext services.

Important: Call UseMiddleware before adding the configuration to the services. UseMiddleware provides more informative error messages if the middleware is registered multiple times compared to a standard service duplicate key exception.

public static class FluentValidationMiddleware
{
    public static AppRunner UseFluentValidation(this AppRunner appRunner, bool showHelpOnError = false)
    {
        return appRunner.Configure(c =>
        {
            // 1. Register the middleware first
            c.UseMiddleware(ValidateModels, MiddlewareSteps.FluentValidation);
            // 2. Add the config to services second
            c.Services.Add(new Config(showHelpOnError));
        });
    }
    
    private class Config
    {
        public bool ShowHelpOnError { get; }
        public Config(bool showHelpOnError) => ShowHelpOnError = showHelpOnError;
    }

    private static Task<int> ValidateModels(CommandContext ctx, ExecutionDelegate next)
    {
        // Access config via services
        var showHelpOnError = ctx.AppConfig.Services.GetOrThrow<Config>().ShowHelpOnError;
        ...
        return next(ctx);
    }
}

CommandDotNet handles argument optionality and default values differently depending on whether the argument is defined as a method parameter or a class property.

Parameters

When defining arguments as method parameters, behavior is consistent for both struct and class types:

• Defaults: Uses the optional parameter value provided in the method signature.
• Optionality: An argument is considered optional if the parameter is marked as Nullable or is an optional parameter in the C# signature.

Properties

When defining arguments as properties, behavior depends on the type:

• Defaults: Uses the property value immediately after initialization.
• Optionality (Structs): A struct property is considered optional if it is Nullable or if its current value is not equal to default(T).
• Optionality (Classes): A class property is considered optional if its current value is not null.

Summary Table

The Password type is used to define arguments that contain sensitive data. It provides two security features to prevent accidental leakage:

1. Serialization Protection: The actual value is only accessible via the GetPassword() method. Because it is not exposed via a standard property, serializers will not automatically capture the sensitive value.
2. Masked Output: The ToString() method is overridden to output ***** if a value is present (or an empty string if no value is provided). This allows logs to show that a password was provided without revealing the actual content or its length.

To access the actual sensitive string, you must call .GetPassword() on the Password instance.

public void Login(IConsole console, string username, Password password)
{
    // password.ToString() will output '*****'
    console.WriteLine($"u:{username} p:{password}");

    // Use GetPassword() to retrieve the actual value
    string actualPassword = password.GetPassword();
}