CommandDotNet_5.0.1

#318 (comment)

CommandDotNet

5.0.1

remove nuget package refs no longer required after move to net5.0

5.0.0

Highlights

NRT

CommandDotNet now supports Nullable reference types (NRT) when calculating Arity. Arityfor.Minimum will be 0 for NRTs.

target net5.0

CommandDotNet targets net5.0 instead of netstandard2.0. This will allow us to take advantage of new framework features.
We're holding off on net6.0 at the moment because it's new enough many companies will not be able to adopt it yet.
We are eager to take advantage of Source Generators though so we will likely also target net6.0 in early 2022.

Windows and Powershell conventions

Added support for Windows and Powershell conventions when using options

• backslash /help and /h for windows conventions
• single hypen -help for long names for powershell conventions

These are not enabled by default. Enable by setting AppSettings.Parser.AllowBackslashOptionPrefix and/or AppSettings.Parser.AllowSingleHyphenForLongNames = true.

Support negative numbers as arguments

Previously, negative numbers were only support when proceeded by : or =, eg --amount=-15 which meant they could only be used with options. CommandDotNet now supports --amount -15 or -15 as an operand.

IConsole

Overhaul of IConsole, now covering most the System.Console members. Converted In, Out and Error to TextReader and TextWriter to match System.Console.
This includes updates to the TestConsole and AnsiTestConsole for the Spectre integration.

Overhaul of IConsole, now covering most the System.Console members. Converted In, Out and Error to TextReader and TextWriter to match System.Console.
This includes updates to the TestConsole and AnsiTestConsole for the Spectre integration.

Breaking Changes in behavior

NRT support

The behavior for calculating Arity and prompting on missing arguments changes as these arguments were not previously considered nullable and so the Arity has changed to expect a minimum of 0 instead of 1

Using the UseArgumentPrompter will now work as expected when using NRTs. They will no longer prompt the user.

ArgumentArity.AllowsNone() change

This has been a confusing method. It currently evaluates as arity.Maximum == 0 but it intuitively it makes more sense as arity.Minimum == 0.

ArgumentArity.AllowsNone() has been changed to arity.Minimum == 0

ArgumentArity.RequiresNone() has been added for arity.Maximum == 0.

Breaking Changes in API

For application developers

Obsoleted cleanup

• removed DefaultMethodAttribute. Use DefaultCommandAttribute instead.
• removed appRunner.UsePrompting(...) extension method. Use .UseIPrompter and .UseArgumentPrompter instead.
• removed BooleanMode.Unknown. Use either Implicit, Explicit, or BooleanMode? instead.

Localizable Resources

Several updates to localizeable Resources. Changed a few member names for clarity and anded a several new members.

AppSettings

• Added AppSettings.Parser
• Moved IgnoreUexpectedOperands to AppSettings.Parser.IgnoreUnexpectedOperands

For middleware developers

IArgument updates

• added BooleanMode properties to help determine the Arity for an argument.
• BooleanMode will only be set for boolean arguments

IConsole updates

• added numerous members to bring closer to parity with System.Console
• removed StandardStreamReader and StandardStreamWriter
• added ForwardingTextWriter to support integrations where text forwards to another console utility, such as Spectre's AnsiConsole
• SystemConsole and TestConsole can be inherited for simpler adaptation resiliant to breakimg changes in IConsole if new members are added

DefaultSources.AppSetting.GetKeysFromConvention

Now takes AppSettings to support / and - option prefixes.

TokenType.Option removed

To support negative numbers and prefixing options with / and -, we needed more context from the command definition so determining if a token is an option or value has been moved to the command parser. Token transformation no longer distinguishes options vs values.

• TokenType.Option and TokenType.Value have merged into TokenType.Argument
• OptionTokenType and Token.OptionTokenType have been removed
• Clubbed options are no longer split during token transformation
• Option assignments are no longer separated during token transformation
• Tokenizer.TryTokenizeOption has been removed

IInvocation updates

added IsInterceptor property to distinguish between command and interceptor invocations

Obsoleted cleanup

• removed ArgumentArity.Default(Type, ...). Use ArgumentArity.Default(IArgument) instead. This is a reversal of previous direction, but the addition of IArgument.BooleanMode makes this reliable.
• removed FindOption(string alias). Use Find<Option>(string alias) instead.
• removed command.GetIgnoreUnexpectedOperands(AppSettings). Use command.IgnoreUnexpectedOperands as it now defaults from AppSettings.
• removed command.GetArgumentSeparatorStrategy(AppSettings). Use command.ArgumentSeparatorStrategy as it now defaults from AppSettings.
• removed Option.ShowInHelp. Use Option.Hidden instead. There were cases where this had meaning outside of generating help.

Version 4

Nullable Reference Types

The library has been updated to support Nullable Reference Types

Default behavior changes

Version 4 is removing obsolete members and changing default behaviors made possible since the v3 was introduced.

• default AppSettings.Help.ExpandArgumentsInUsage to true.
  • arguments are expanded in the usage section of help.
    • old: add [options] [arguments]
    • new: add [options] <x> <y>
• default AppSettings.DefaultArgumentSeparatorStrategy to EndOfOptions. See Argument Separator for details.
  • Help will append [[--] <arg>...] to the usage example when DefaultArgumentSeparatorStrategy=PassThru
• make AppSettings.LongNameAlwaysDefaultsToSymbolName the only behavior and remove the setting. LongName can be removed with [Option(LongName=null)].
  • Look for places in your apps where [Option(ShortName="a")] with setting a LongName. If you don't want a LongName then add LongName=null otherwise the long name will default from the parameter or property name.
• make AppSettings.GuaranteeOperandOrderInArgumentModels the only behavior and remove the setting.
  • see this Argument Models section for details
• enable CommandLogger in .UseDefaultMiddleware() as cmdlog directive. This can be useful for diagnostics.
• Command.FindOption will throw an exception if the alias is for an operand or subcommand instead of an option. Previously it would return null.

Added

• The type MiddlewareSteps declares most of the framework defined middleware to make it easier to inject your custom middleware in the desired order.

Changed

• When registering middleware, the OrderInStage parameter has been changed from int to short.

Moved

• CommandDotNet.Directives.Parse.ParseReporter - moved to CommandDotNet.Diagnostics.Parse.ParseReporter
• CommandDotNet.Directives.Debugger - moved to CommandDotNet.Diagnostics.Debugger
• AppConfig.CancellationToken - moved to CommandDotNet.CancellationToken. This enables running nested commands within an interactive session. See Ctrl+C and CancellationToken for more details.

Removed or Replaced

• AppSettings
  • MethodArgumentMode - replaced by DefaultArgumentMode
  • ThrowOnUnexpectedArgument - replaced by IgnoreUnexpectedArguments
  • AllowArgumentSeparator - was never used for functionality, only to show -- in help.
  • HelpTextStyle - replaced by Help.TextStyle
  • Help
    • GlobalTool - replaced by UsageAppName
• VersionInfo - replaced by AppInfo
• ApplicationMetadataAttribute - replaced by CommandAttribute
• ArgumentAttribute - replaced by OperandAttribute
• ArgumentMode.Parameter - replaced by Operand
• InjectPropertyAttribute - v3 made ctor injection possible and that should be used.
• Command, Option, Operand ctor taking with Command parent parameter. Parent is now assigned by adding to a command.
• OptionAttribute
  • Inherited - replaced by AssignToExecutableSubcommands
• Option
  • DefaultValue - use Option.Default
  • Inherited - replaced by AssignToExecutableSubcommands
• Operand
  • DefaultValue - use Option.Default
• IArgument
  • DefaultValue - use Option.Default
• appRunner.UseDefaultsFromConfig extension method that returns string, in favor of method with same name returning ArgumentDefault
• TokenCollection public ctor - Use Tokenizer.Tokenize extension method to generate tokens and TokenCollection.Transform to transform them. Ensures source tokens are correctly mapped.
• AnsiConsole - no longer supported. Use a package like ColorConsole or Pastel.
• MiddlewareSteps.Help.Stage & MiddlewareSteps.Help.Order - replaced by nested MiddlewareSteps.Help classes
• ServicesExtensions.GetOrAdd<T> - use ContextDataExtensions.GetOrAdd<T>

v3.0.1

Enhancements

• #199 CommandDotNet stacktraces no longer include build system filepaths. Thank you @asymetrixs
• #197 add %UsageAppName% template to use in Description, ExtendedHelpText & Usage overrides.

Fixed

• #197 support for self-contained executables. Usage example will show the executable name instead of inner dll.

v3.0.0

see What's new in version 3 for an overview of the updates

CommandDotNet_3.0.0-preview9

Breaking change for preview:

UseDependencyInjector signature changed: ddf5295

change your usages as follows
useResolveForArgumentModel = true -> argumentModelResolveStrategy = ResolveStrategy.Resolve
useTryResolveForCommandClass = true -> commandClassResolveStrategy = ResolveStrategy.TryResolve

CommandDotNet.IoC.SimpleInjector_2.0.0-preview3

Breaking change for preview:

UseSimpleInjector signature changed: ddf5295

change your usages as follows
useResolveForArgumentModel = true -> argumentModelResolveStrategy = ResolveStrategy.Resolve
useTryResolveForCommandClass = true -> commandClassResolveStrategy = ResolveStrategy.TryResolve

CommandDotNet.IoC.MicrosoftDependencyInjection_2.0.0-preview3

Breaking change for preview:

UseMicrosoftDependencyInjection signature changed: ddf5295

change your usages as follows
useResolveForArgumentModel = true -> argumentModelResolveStrategy = ResolveStrategy.Resolve
useTryResolveForCommandClass = true -> commandClassResolveStrategy = ResolveStrategy.TryResolve

CommandDotNet.IoC.Autofac_2.0.0-preview3

Breaking change for preview:

UseAutofac signature changed: ddf5295

change your usages as follows
useResolveForArgumentModel = true -> argumentModelResolveStrategy = ResolveStrategy.Resolve
useTryResolveForCommandClass = true -> commandClassResolveStrategy = ResolveStrategy.TryResolve

2.7.7-beta

#55 : add idisposable support

2.7.5

release