"Building intuitive command-line interfaces in .NET", Alex Thissen
0 likes246 views
This document discusses CLIs (command line interfaces) and how they can be implemented in .NET. It provides an overview of the benefits of CLIs such as efficiency, automation, and cross-platform support. It then demonstrates how to build CLIs using .NET libraries like System.CommandLine, which provides object models for defining commands, arguments, options and handling command line parsing and execution. Features like middleware, error handling, suggestions and help are demonstrated. Best practices for CLIs like intuitiveness and discoverability are also covered.
![Debugging tips
Use [debug] directive
Attach debugger to start debug session from terminal
Pass arguments from dotnet to your CLI
{
"profiles": {
"AdvancedCLI": {
"commandName": "Project",
"commandLineArgs": "help",
"environmentVariables": {
"DOTNET_COMMANDLINE_DEBUG_PROCESSES": "ale"
ale.exe [debug] .Zarlor.lnx --magnification 3 –f --controller keyboard
dotnet run -- .Zarlor.lnx --magnification 3 –f --controller keyboard
Possible error
Debug directive specified, but no process names are listed as allowed for debug.
Add your process name to the 'DOTNET_COMMANDLINE_DEBUG_PROCESSES' environment variable.
The value of the variable should be the name of the processes, separated by a semi-colon
';', for example 'DOTNET_COMMANDLINE_DEBUG_PROCESSES=ale'
Hint:
Try [parse] and [suggest]](https://image.slidesharecdn.com/buildingintuitiveclisin-210810094141/85/Building-intuitive-command-line-interfaces-in-NET-Alex-Thissen-19-320.jpg)
"Building intuitive command-line interfaces in .NET", Alex Thissen
- 2. The rise of CLIs Graphical User Interface Command-line Interface Efficiency Fast and simple interaction model Low level access in single line commands Basic text-driven command line Automation Scriptable Integration in CI/CD pipelines Cross-platform Terminal-based or headless environments do not have GUI Allows porting to Windows, Linux and MacOS User experience Rich UI and UX Many visualizations
- 3. Examples of CLIs and tools CLIs dotnet az docker kubectl tye git npm Tools curl python Interactive netsh mssql-cli telnet
- 4. Demo Exploring CLIs Easter egg: Windows Terminal Quake Mode: + `
- 5. Command syntax ale.exe .Zarlor.lnx --magnification 3 –f --controller keyboard Options - Key-value pairs - Short and long form names - Delimited by space, colon or equal sign - Style: POSIX -- or Windows / - Combine single char option - Arity Arguments - Required values in specific order - Arity (unary, binary, …)
- 6. Command-line lifecycle Parsing and invoking Tokenization Value conversion Create context Execution Run middleware pipeline Handler run logic Building and preparing Define commands, arguments and options Configuration Input Command-line Response file Tab-completion Feedback Progress updates Prompting Rendering output Termination Exception handling Return exit codes Report errors Provide help and suggestions
- 7. Host process Implementing CLIs in .NET Application code Recommended packages • System.CommandLine • CliFx • Spectre.Console.Cli • CommandLineParser Terminal or script
- 8. System.CommandLine object model Prepare commands Build command-line Symbols Hierarchy of symbols Name (and aliases for identifier symbols) Other types Parse & Invoke
- 9. Demo Building command-lines and parsers Create commands, arguments and options
- 10. Command handling Provide handler function per command Create handler using factory methods Delegate or separate function Model binding used by default rootCommand.Handler = CommandHandler.Create<InvocationContext, int, bool>( (context, magnification, fullScreen) => { context.Console.Out.Write($"Magnification: {magnification} FullScreen {fullScreen}"); });
- 11. Middleware pipeline ExceptionHandler Out-of-the-box 1. CancelOnProcessTermination 2. ExceptionHandler 3. EnvironmentVariableDirective 4. ConfigureConsole 5. RegisterWithDotnetSuggest 6. DebugDirective 7. ParseDirective 8. SuggestDirective Out-of-the-box 9. TypoCorrections 10. VersionOption 11. HelpOption Configuration Default ErrorReporting Your middleware logic Invocation context Out-of-the-box 12. ParseErrorReporting
- 12. Registering middleware Extension methods on CommandLineBuilder Resembles ASP.NET Core middleware Various Use… methods Prioritize with MiddlewareOrder enumeration Parser parser = new CommandLineBuilder(rootCommand) .UseDefaults() .UseMiddleware(async (context, next) => { // Execute your middleware logic here await next(context); }, MiddlewareOrder.ErrorReporting) .Build(); Order of registration More than one custom middleware allowed Beware of defaults Production version might need to skip some default middleware (for example: directives)
- 13. ale.exe .Zarlor.lnx –-full-screen -m 3 --controller keyboard Model binding Run(FileInfo gameRom, int magnification, bool fullScreen, ControllerType controller) In-order named arguments Named options Case insensitive Kebab casing supported Ignores hyphens and other prefixes Boolean, enumerations (case-insensitive) Enumerable types (arrays, lists, …) String based constructors (FileInfo, DirectoryInfo, Uri) Complex types (based on properties or constructor)
- 14. Data types conversion Special types are bound automatically IConsole Abstraction for out and err ParseResult All results of parsing tokens command-line CancellationToken Cancel async tasks BindingContext Captures converted typed values InvocationContext Combines all of the above Run( … , ControllerType controller, BindingContext context, CancellationToken token) Simply add to command handler signature
- 15. Demo: Advanced scenarios Error handling and termination Middleware Subcommands and global options Common patterns
- 16. Making it intuitive Intuitive CLIs CLI-first approach Standards and conventions Simplicity Discoverability Offer help and documentation from CLI Defaults save time and better for learning Suggestions and typo corrections Familiar names of arguments and options Default to stderr and stdout First client application is a CLI More human-oriented: Ad-hoc tasks and quick Split a complex system into many small functions Assign each function into a simple command
- 17. Help Get contextual help for free Description Available names Required and arity Allowed values and default value Provide custom help Create your own help builder Register with .UseHelp<THelpBuilder>
- 18. Suggestions and typo corrections Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentSession dotnet tool install --global dotnet-suggest --version 1.1.221601 Terminal session Interactive Host process PowerShell bash zsh dotnet- suggest Global dotnet tool • Shell completions (aka tab completions) • Register small script in bash or PowerShell profile Suggestion sources • Enums and known values automatically added • Can add custom suggestions through ISuggestionSource Pro tip: DOTNET_SUGGEST_LOGGING 1 DOTNET_SUGGEST_SCRIPT_VERSION 1.0.1
- 19. Debugging tips Use [debug] directive Attach debugger to start debug session from terminal Pass arguments from dotnet to your CLI { "profiles": { "AdvancedCLI": { "commandName": "Project", "commandLineArgs": "help", "environmentVariables": { "DOTNET_COMMANDLINE_DEBUG_PROCESSES": "ale" ale.exe [debug] .Zarlor.lnx --magnification 3 –f --controller keyboard dotnet run -- .Zarlor.lnx --magnification 3 –f --controller keyboard Possible error Debug directive specified, but no process names are listed as allowed for debug. Add your process name to the 'DOTNET_COMMANDLINE_DEBUG_PROCESSES' environment variable. The value of the variable should be the name of the processes, separated by a semi-colon ';', for example 'DOTNET_COMMANDLINE_DEBUG_PROCESSES=ale' Hint: Try [parse] and [suggest]
- 20. Photo by Pavel Mata on Unsplash DragonFruit Quick and easy way to create a simple CLI Add reference to NuGet package System.CommandLine.DragonFruit Change Main method to include typed arguments Must return void, int, Task or Task<int> Provide XML documentation as help information static int Main(FileInfo gameRom, bool fullScreen = false, int magnification = 4, ControllerType controller = ControllerType.Keyboard, FileInfo bootRom = null) /// <summary> /// Atari Lynx Emulator from DragonFruit /// </summary> /// <param name="gameRom">Game ROM filename</param> /// <param name="fullScreen">Run emulator fullscreen</param>
- 22. Console is not your average console Error, Out and In should be used Avoid System.Console Use provided abstraction instead (IConsole) TestConsole in unit tests Respect redirection Input might come from response file Output might be sent to file or elsewhere Test output with pipes Output and rendering Convenient: Include System.CommandLine.IO for extension methods on Error and Out
- 23. Terminal GUIs for CLIs Rich interaction with user Remember: CLI != GUI
- 24. Comparing CLI frameworks (opinionated) System.CommandLine Spectre.Console.Cli CommandLineParser CliFx Hierarchical commands Yes Yes Limited Yes Suggestions and typo corrections Yes No No No Help Autogenerated Autogenerated Autogenerated Autogenerated Target framework .NET Standard 2.0 .NET Standard 2.0 .NET 5.0 .NET Standard 2.0 .NET 4.0, 4.5, 4.6.1 .NET Standard 2.0, 2.1 Version 2.0.0-beta1.21308.1 0.49.0 2.9.0-preview1 2.0.6 Maintainer activity Binding ++ + + ++ Host integration ++ + - ++ Directives debug, parse, config None None debug, parse
- 25. Summary {DevOps} $ CLI <3 .NET --always
- 26. Questions and Answers During Discord Q&A session Maybe later? @alexthissen athissen@xpirit.com