Skip to content

AppSettings Reference#

AppSettings is the central configuration object for customizing CommandDotNet behavior. It contains nested settings objects for different aspects of the framework.

How to Configure#

AppSettings are configured when creating the AppRunner:

private static AppRunner ConstructorMethod()
{
    return new AppRunner<Program>(new AppSettings
    {
        Help = { PrintHelpOption = true }
    });
}
snippet source | anchor

Or using the Configure method:

private static AppRunner ConfigureMethod()
{
    return new AppRunner<Program>()
        .Configure(b => b.AppSettings.Help.PrintHelpOption = true);
}
snippet source | anchor

Settings Categories#

Arguments Settings#

AppSettings.Arguments - Controls argument parsing and behavior

/// <summary>
/// When Explicit, boolean options require a 'true' or 'false' value be specified.<br/>
/// When Implicit, boolean options are treated as Flags, considered false unless it's specified
/// and the next argument will be considered a new argument.
/// </summary>
public BooleanMode BooleanMode { get; set; } = BooleanMode.Implicit;

/// <summary>
/// When arguments are not decorated with <see cref="OperandAttribute"/> or <see cref="OptionAttribute"/>
/// DefaultArgumentMode is used to determine which type of argument to assign.
/// <see cref="ArgumentMode.Operand"/> is the default.
/// </summary>
public ArgumentMode DefaultArgumentMode { get; set; } = ArgumentMode.Operand;

/// <summary>
/// Character used to split the option values into substrings.
/// Setting it here will enable for all options that accept multiple values.<br/>
/// The character can be set and overridden for each option in the <see cref="OptionAttribute"/>
/// or <see cref="NamedAttribute"/>. 
/// </summary>
public char? DefaultOptionSplit { get; set; }

/// <summary>
/// Symbol used to indicate piped content should be directed to a specific argument.
/// If not specified when executing a command, piped input will be directed to
/// the final operand if it is a list.
/// </summary>
public string? DefaultPipeTargetSymbol { get; set; } = "^";

/// <summary>
/// When true, arity is not validated.
/// Arity validation will also be skipped if the application does not support
/// <see href="https://docs.microsoft.com/en-us/dotnet/csharp/nullable-references">NRTs</see>.
/// </summary>
public bool SkipArityValidation { get; set; }
snippet source | anchor

Parser Settings#

AppSettings.Parser - Controls how arguments are parsed

/// <summary>
/// The default <see cref="ArgumentSeparatorStrategy"/>.
/// This can be overridden for a <see cref="Command"/> using the <see cref="CommandAttribute"/>
/// </summary>
public ArgumentSeparatorStrategy DefaultArgumentSeparatorStrategy { get; set; } = ArgumentSeparatorStrategy.EndOfOptions;

/// <summary>
/// When false, unexpected operands will generate a parse failure.<br/>
/// When true, unexpected arguments will be ignored and added to <see cref="ParseResult.RemainingOperands"/><br/>
/// </summary>
public bool IgnoreUnexpectedOperands { get; set; }

public bool AllowBackslashOptionPrefix { get; set; }

public bool AllowSingleHyphenForLongNames { get; set; }
snippet source | anchor

Commands Settings#

AppSettings.Commands - Controls command discovery and execution

/// <summary>When true, methods on base classes will be included as commands.</summary>
public bool InheritCommandsFromBaseClasses { get; set; }
snippet source | anchor

Help Settings#

AppSettings.Help - Customizes help generation

/// <summary>When true, the help option will be included in the help for every command</summary>
public bool PrintHelpOption { get; set; }

/// <summary>Specify whether to use Basic or Detailed help mode. Default is Detailed.</summary>
public HelpTextStyle TextStyle { get; set; } = HelpTextStyle.Detailed;

internal void SetExecutionSettings(ExecutionAppSettings executionSettings) => _executionSettings = executionSettings;

/// <summary>Specify what AppName to use in the 'Usage:' example</summary>
[Obsolete("Use AppSettings.Execution.UsageAppNameStyle")]
public UsageAppNameStyle UsageAppNameStyle
{
    get => _executionSettings?.UsageAppNameStyle ?? UsageAppNameStyle.Adaptive;
    set { if (_executionSettings != null) _executionSettings.UsageAppNameStyle = value; }
}

/// <summary>
/// The application name used in the Usage section of help documentation.<br/>
/// When specified, <see cref="UsageAppNameStyle"/> is ignored.
/// </summary>
[Obsolete("Use AppSettings.Execution.UsageAppName")]
public string? UsageAppName
{
    get => _executionSettings?.UsageAppName;
    set { if (_executionSettings != null) _executionSettings.UsageAppName = value; }
}

/// <summary>
/// When true, the usage section will expand arguments so the names of all arguments are shown.
/// </summary>
public bool ExpandArgumentsInUsage { get; set; } = true;
snippet source | anchor

Note

Additional obsolete properties UsageAppNameStyle and UsageAppName have been moved to AppSettings.Execution

Execution Settings#

AppSettings.Execution - Controls command execution

/// <summary>Specify what AppName to use in usage examples, help text, and generated scripts</summary>
public UsageAppNameStyle UsageAppNameStyle { get; set; } = UsageAppNameStyle.Adaptive;

/// <summary>
/// The application name used in usage examples, help text, and generated scripts.<br/>
/// When specified, <see cref="UsageAppNameStyle"/> is ignored.
/// </summary>
public string? UsageAppName { get; set; }
snippet source | anchor

Localization Settings#

AppSettings.Localization - Configure localization behavior

/// <summary>When specified, this function will be used to localize user output from the framework</summary>
public Func<string,string?>? Localize { get; set; }

/// <summary>
/// By default, the keys passed to the <see cref="Localize"/> delegate
/// are the values define in the Resources class.<br/>
/// Setting this to true will use the property or method names instead of the values.<br/>
/// Example: for property - `Common_argument_lc => "argument"`<br/>
/// the default key is "argument".<br/>
/// When <see cref="UseMemberNamesAsKeys"/> is set to true, "Common_argument_lc" is the key.
/// </summary>
public bool UseMemberNamesAsKeys { get; set; }
snippet source | anchor

Common Configuration Patterns#

All Arguments as Options#

Make all arguments named by default:

private static AppSettings AllArgumentsAsOptions = new AppSettings
{
    Arguments = { DefaultArgumentMode = ArgumentMode.Option }
};
snippet source | anchor

Explicit Boolean Values#

Require users to specify true/false for boolean options:

private static AppSettings ExplicitBooleanValues = new AppSettings
{
    Arguments = { BooleanMode = BooleanMode.Explicit }
};
snippet source | anchor

Windows-style Options#

Support /option syntax:

private static AppSettings WindowsStyleOptions = new AppSettings
{
    Parser = { AllowBackslashOptionPrefix = true }
};
snippet source | anchor

PowerShell-style Options#

Support -longname syntax:

private static AppSettings PowerShellStyleOptions = new AppSettings
{
    Parser = { AllowSingleHyphenForLongNames = true }
};
snippet source | anchor

Expanded Help#

Show argument names in usage:

private static AppSettings ExpandedHelp = new AppSettings
{
    Help = 
    { 
        ExpandArgumentsInUsage = true,
        PrintHelpOption = true
    }
};
snippet source | anchor

Disable Directives#

Turn off directive support (e.g., [debug], [parse]):

private static AppSettings DisableDirectives = new AppSettings
{
    DisableDirectives = true
};
snippet source | anchor

Tips#

  1. Start with defaults: Only override settings you actually need
  2. Document your choices: Explain non-standard configurations in code comments
  3. Test early: Configure AppSettings early in development to avoid surprises
  4. Consider users: Think about how settings affect the user experience