- Added console dimension properties
WindowWidth
andWindowHeight
toIConsole
interface and implementing classes. - Improved inline documentation for members of
IConsole
interface.
- Added an overload of
CliApplicationBuilder.UseTypeActivator(...)
that accepts an instance ofIServiceProvider
. This slightly simplifies integration with many DI containers. - Fixed minor grammar mistakes in user-facing error messages.
- Updated default value resolution for the application executable name. It will now resolve to
myapp.exe
instead ofdotnet myapp.dll
when the application is launched through the EXE apphost on Windows. On other platforms, or when running the application through the .NET CLI, the behavior will be the same as before.
- Added more contextual information to analyzer diagnostics.
- Fixed an issue where the analyzer incorrectly reported an error on converters that didn't directly match the target type but were compatible through known built-in conversions.
- Fixed an issue where MSBuild produced a lot of analyzer-related warnings in certain circumstances.
- Changed method signature of
IConsole.ReadKey()
to returnConsoleKeyInfo
instead ofvoid
. The return type was originally defined asvoid
by mistake. This change is source-backwards-compatible but may break on binary level if you were previously calling this method indirectly (i.e. through a library). - Added
FakeConsole.EnqueueKey(...)
to facilitate the testing ofIConsole.ReadKey()
. You can use this method to simulate key presses in your application. - Extended analyzers that verify the correctness of specified converters and validators. They now also ensure that the specified types are compatible with the type of the underlying property.
- Improved diagnostics produced by analyzers. Where relevant, highlighted code is now limited to the property or type identifier, instead of the whole property or type declaration. Also extended the diagnostic messages with additional information.
- Fixed an issue where throwing an exception inside a constructor of a command type resulted in an unrelated error message about the absence of a parameterless constructor.
- Fixed an issue where
ConsoleWriter
andConsoleReader
were not properly thread-safe. - Fixed an issue where the analyzer failed to load under certain circumstances when running inside Visual Studio.
- Fixed an issue which caused help text to not show default values for optional parameters. (Thanks @AliReZa Sabouri)
- Added support for optional parameters. A parameter can be marked as optional by setting
IsRequired = false
on the attribute. Only one parameter is allowed to be optional and such parameter must be the last in order. (Thanks @AliReZa Sabouri) - Fixed an issue where parameters and options bound to properties implemented as default interface members were not working correctly. (Thanks @AliReZa Sabouri)
- Added
IConsole.Clear()
with corresponding implementations inSystemConsole
,FakeConsole
, andFakeInMemoryConsole
. (Thanks @Alex Rosenfeld) - Added
IConsole.ReadKey()
with corresponding implementations inSystemConsole
,FakeConsole
, andFakeInMemoryConsole
. (Thanks @Alex Rosenfeld) - Fixed an issue that caused parameters to appear out of order in the usage format section of the help text. (Thanks @David Fallah)
- Fixed an issue where an exception thrown via reflection during parameter or option binding resulted in
Exception has been thrown by the target of an invocation
error instead of a more useful message. Such exceptions will now be unwrapped to provide better user experience.
- Fixed an issue where calling
IConsole.Output.Encoding.EncodingName
and some other members threw an exception. - Added readme file to the package.
- Fixed an issue where output and error streams in
SystemConsole
defaulted to UTF8 encoding with BOM when the application was running with UTF8 codepage.ConsoleWriter
will now discard preamble from the specified encoding. This fix brings the behavior ofSystemConsole
in line with .NET's ownSystem.Console
which also discards preamble for output and error streams. - Fixed an issue where help text tried to show default values for parameters and options whose type does not override
ToString()
method. - Fixed an issue where help text didn't show default values for parameters and options whose type is an enumerable of nullable enums. (Thanks @Robert Dailey)
- Fixed an issue where specific parts of the help text weren't legible in some terminals due to low color resolution. Removed the usage of
ConsoleColor.DarkGray
in help text.
- Improved help text by showing valid values for non-scalar enum parameters and options. (Thanks @Robert Dailey)
- Fixed an issue where having a transitive reference to CliFx sometimes resulted in
SystemConsoleShouldBeAvoidedAnalyzer
throwingNullReferenceException
during build. - Fixed some documentation typos and inconsistencies.
- Fixed an issue where some exceptions with async stack traces generated on .NET 3.1 or earlier were not parsed and formatted correctly.
- Fixed an issue where help text applied slightly incorrect formatting when displaying choices for enum-based parameters and properties.
Note: this major release includes many breaking changes. Please refer to the readme to find updated instructions and usage examples.
- Renamed property
EnvironmentVariableName
toEnvironmentVariable
onCommandOption
attribute. - Removed most of schema validation checks that used to take place during application startup. Going forward, CliFx will be relying solely on its built-in set of Roslyn analyzers to catch common errors in command configuration.
- Removed
ProgressTicker
utility. The recommended migration path is to use the Spectre.Console library which provides a wide array of console widgets and components. See this wiki page to learn how to integrate Spectre.Console with CliFx. - Removed
MemoryStreamWriter
utility as it's no longer used within CliFx. - Improved wording in all error messages.
- Renamed some methods on
CliApplicationBuilder
:UseTitle()
renamed toSetTitle()
UseExecutableName()
renamed toSetExecutableName()
UseVersionText()
renamed toSetVersion()
UseDescription()
renamed toSetDescription()
- Changed the behavior of autogenerated help text:
- Changed the color scheme to a more neutral set of tones
- Assigned separate colors to parameters and options to make them visually stand out
- Usage section no longer lists usage formats of all descendant commands
- Command section now also lists available subcommands for each of the current command's subcommands
- Changed the behavior of
[preview]
directive. Running the application with this directive will now also print all resolved environment variables, in addition to parsed command line arguments. - Reworked
IArgumentValueConverter
/ArgumentValueConverter
intoBindingConverter
. MethodConvertFrom(...)
has been renamed toConvert(...)
. - Reworked
ArgumentValueValidator
intoBindingValidator
. This class exposes an abstractValidate(...)
method that returns a nullableBindingValidationError
. This class also provides utility methodsOk()
andError(...)
to help create corresponding validation results. - Changed the type of
IConsole.Output
andIConsole.Error
fromStreamWriter
toConsoleWriter
. This type derives fromStreamWriter
and additionally exposes aConsole
property that refers to the console instance that owns the stream. This change enables you to author extension methods scoped specifically to console output and error streams. - Changed the type of
IConsole.Input
fromStreamReader
toConsoleReader
. This type derives fromStreamReader
and additionally exposes aConsole
property that refers to the console instance that owns the stream. This change enables you to author extension methods scoped specifically to the console input stream. - Changed methods
IConsole.WithForegroundColor(...)
,IConsole.WithBackgroundColor(...)
, andIConsole.WithColors(...)
to returnIDisposable
, replacing the delegate parameter they previously had. You can wrap the returnedIDisposable
in a using statement to ensure that the console colors get reset back to their original values once the execution reaches the end of the block. - Renamed
IConsole.GetCancellationToken()
toIConsole.RegisterCancellationHandler()
. - Reworked
VirtualConsole
intoFakeConsole
. This class no longer takesCancellationToken
as a constructor parameter, but instead encapsulates its own instance ofCancellationTokenSource
that can be triggered using the providedRequestCancellation()
method. - Removed
VirtualConsole.CreateBuffered()
and replaced it with theFakeInMemoryConsole
class. This class derives fromFakeConsole
and uses in-memory standard input, output, and error streams. It also provides methods to easily read the data written to the streams. - Moved some types to different namespaces:
IConsole
/FakeConsole
/FakeInMemoryConsole
moved fromCliFx
toCliFx.Infrastructure
ITypeActivator
/DefaultTypeActivator
/DelegateTypeActivator
moved fromCliFx
toCliFx.Infrastructure
BindingValidator
/BindingConverter
moved fromCliFx
toCliFx.Extensibility
- Added support for custom value validators. You can now create a type that inherits from
CliFx.ArgumentValueValidator<T>
to implement reusable validation logic for command arguments. To use a validator, include it in theValidators
property on theCommandOption
orCommandParameter
attribute. (Thanks @Oleksandr Shustov) - Added
CliFx.ArgumentValueConverter<T>
class that you can inherit from to implement custom value converters.CliFx.IArgumentValueConverter
interface is still available, but it is recommended to inherit from the generic class instead, due to the type safety it provides. The interface may become internal or get removed in one of the future major versions. - Updated requirements for option names and short names: short names now must be letter characters (lowercase or uppercase), while names must now start with a letter character. This means option names can no longer start with a digit or a special character. This change makes it possible to pass negative number values without the need to quote them, i.e.
--my-number -5
.
- Added pretty-printing for unhandled exceptions thrown from within the application. This makes the errors easier to parse visually and should help in troubleshooting. This change does not affect
CommandException
, as it already has special treatment. (Thanks @Mårten Åsberg) - Added support for custom value converters. You can now create a type that implements
CliFx.IArgumentValueConverter
and specify it as a converter for your parameters or options via theConverter
named property. This should enable conversion between raw argument values and custom types which are not string-initializable. (Thanks @Oleksandr Shustov) - Improved help text so that it also shows minimal usage examples for child and descendant commands, besides the actual command it was requested on. This should improve user experience for applications with many nested commands. (Thanks @Nikiforov Alexey)
- Added
VirtualConsole.CreateBuffered()
method to simplify test setup when using in-memory backing stores for output and error streams. Please refer to the readme for updated recommendations on how to test applications built with CliFx. - Added generic
CliApplicationBuilder.AddCommand<TCommand>()
. This overload simplifies adding commands one-by-one as it also checks that the type implementsICommand
.
- Fixed an issue where a command was incorrectly allowed to execute when the user did not specify any value for a non-scalar parameter. Since they are always required, a parameter needs to be bound to at least one value. (Thanks @Daniel Hix)
- Fixed an issue where
CliApplication.RunAsync(...)
threwArgumentException
if there were two environment variables, whose names differed only in case. Environment variable names are now treated case-sensitively. (Thanks @Ron Myers)
- Running the application with the debug directive (
myapp [debug]
) will now also try to launch a debugger instance. In most cases it will save time as you won't need to attach the debugger manually. (Thanks @Volodymyr Shkolka) - Fixed an issue where unhandled generic exceptions (i.e. not
CommandException
) sometimes caused the application to incorrectly return successful exit code due to an overflow issue on Unix systems. Starting from this version, all unhandled generic exceptions will produce1
as the exit code when thrown. Instances ofCommandException
can still be configured to return any specified exit code, but it's recommended to constrain the values between1
and255
to avoid overflow issues. (Thanks @Ihor Nechyporuk)
- Changed analyzers to report errors instead of warnings. If you find that some analyzer works incorrectly, please report it on GitHub. You can also configure inspection severity overrides in your project if you need to.
- Improved help text by showing default values for non-required options. This only works on types that have a custom override for
ToString()
method. Additionally, if the type implementsIFormattable
, the overload with a format provider will be used instead. (Thanks @Domn Werner) - Changed default version text to only show 3 version components instead of 4, if the last component (revision) is not specified or is zero. This makes the default version text compliant with semantic versioning.
- Fixed an issue where it was possible to define a command with an option that has the same name or short name as built-in help or version options. Previously it would lead to the user-defined option being ignored in favor of the built-in option. Now this will throw an exception instead.
- Changed the underlying representation of
StreamReader
/StreamWriter
objects used inSystemConsole
andVirtualConsole
to be thread-safe.
- Added built-in Roslyn analyzers that help catch incorrect usage of the library. Currently, all analyzers report issues as warnings so as to not prevent the project from building. In the future that may change.
- Added an optional parameter to
new CommandException(...)
calledshowHelp
which can be used to instruct CliFx to show help for the current command after printing the error. (Thanks @Domn Werner) - Improved help text shown for enum options and parameters by providing the list of valid values that the enum can accept. (Thanks @Domn Werner)
- Fixed an issue where it was possible to set an option without providing a value, while the option was marked as required.
- Fixed an issue where it was possible to configure an option with an empty name or a name consisting of a single character. If you want to use a single character as a name, you should set the option's short name instead.
- Added
CursorLeft
andCursorTop
properties toIConsole
and its implementations. InVirtualConsole
, these are just auto-properties. - Improved exception messages.
- Improved exceptions related to user input by also showing help text after the error message. (Thanks @Domn Werner)
- Changed
IConsole
interface (and as a result,SystemConsole
andVirtualConsole
) to support writing binary data. Instead ofTextReader
/TextWriter
instances, the streams are now exposed asStreamReader
/StreamWriter
which provide theBaseStream
property that allows raw access. Existing usages inside commands should remain the same becauseStreamReader
/StreamWriter
are compatible with their base classesTextReader
/TextWriter
, but if you were usingVirtualConsole
in tests, you may have to update it to the new API. Refer to the readme for more info. - Changed argument binding behavior so that an error is produced if the user provides an argument that doesn't match with any parameter or option. This is done in order to improve user experience, as otherwise the user may make a typo without knowing that their input wasn't taken into account.
- Changed argument binding behavior so that options can be set to multiple argument values while specifying them with mixed naming. For example,
--option value1 -o value2 --option value3
would result in the option being set to corresponding three values, assuming--option
and-o
match with the same option.