# Cocona
**Repository Path**: dotnet-cafe/Cocona
## Basic Information
- **Project Name**: Cocona
- **Description**: Micro-framework for .NET console application. Cocona makes it easy and fast to build console applications on .NET.
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-02-07
- **Last Updated**: 2022-02-07
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 
Micro-framework for .NET **Co**re **con**sole **a**pplication. Cocona makes it easy and fast to build console applications on .NET.🚀
[](https://dev.azure.com/misuzilla/Cocona/_build/latest?definitionId=18&branchName=master) [](https://www.nuget.org/packages/Cocona) [](https://www.nuget.org/packages/Cocona.Lite)
### ⏱ Create a console application with Cocona in seconds.
```csharp
CoconaApp.Run((string? name, bool hey) =>
Console.WriteLine("{(hey ? "Hey" :"Hello")} {(name ?? "Guest")}!"));
```
## Feature
- 🚀 **Make it easy to build console applications on .NET.**
- ASP.NET Core-like Minimal API
- `public` method as a command
- Provides ASP.NET Core MVC-like development experience to console application development.
- ✨ **Command-line option semantics like UNIX tools standard. (`getopt`/`getopt_long` like options)**
- Your app can handle both `-rf /` and `-r -f /` :-)
- Support single command and multiple commands style
- `myapp --foo --bar -n arg0 "arg1"` (e.g. `dir`, `cp`, `ls` ...)
- `myapp server -m "Hello world!"` (e.g. `dotnet`, `git`, `kubectl` ...)
- ❓ **Built-in help documentation support.**
- You want to see a help message; you type `-h` or `--help`.
- Built-in similar commands suggestion
- Shell command-line completion support for `bash` and `zsh`
- 🛠 **Highly modulable/customizable CLI framework.**
- Cocona built on top of `Microsoft.Extensions.*` framework. Cocona natively supports Logging, DI, Configuration and ConsoleLifetime.
- Don't you need `Microsoft.Extensions.*`? [then you can use a lightweight version of Cocona (named Cocona.Lite)](#performance--coconalite).
[You can find sample code for various features.](samples)
## Table of contents
- [Installing](#installing)
- [Requirements](#requirements)
- [Getting Started](#getting-started)
- [Command-line handling basics](#command-line-handling-basics)
- [Command](#command)
- [Options](#options)
- [Arguments](#arguments)
- [Sub-commands](#sub-commands)
- [Option-like commands](#option-like-commands)
- [Cocona in action](#cocona-in-action)
- [Parameter set](#parameter-set)
- [Exit code](#exit-code)
- [Validation](#validation)
- [Shutdown event handling](#shutdown-event-handling)
- [Command filter](#command-filter)
- [Dependency Injection](#dependency-injection)
- [Configuration](#configuration)
- [Logging](#logging)
- [Shell command-line completion](#shell-command-line-completion)
- [Performance & Cocona.Lite](#performance--coconalite)
- [Advanced](#advanced)
- [Localization](#localization)
- [Hide command from help](#hide-command-from-help)
- [Help customization](#help-customization)
- [CommandMethodForwardedTo attribute](#commandmethodforwardedto-attribute)
- [IgnoreUnknownOptions attribute](#ignoreunknownoptions-attribute)
- [GenericHost integration](#generichost-integration)
- [Related projects](#related-projects)
- [License](#license)
## Installing
Install NuGet package from NuGet.org
```sh
$ dotnet add package Cocona
# A lightweight version is also available if you prefer less dependency.
$ dotnet add package Cocona.Lite
```
## Requirements
- .NET 6 (Required to use Minimal API)
- .NET 5
- .NET Standard 2.0, 2.1
## Getting Started
```csharp
using Cocona;
CoconaApp.Run((string name) =>
{
Console.WriteLine($"Hello {name}");
})
```
Class-based style (for .NET Standard / .NET 5)
```csharp
using Cocona;
class Program
{
static void Main(string[] args)
{
// Cocona parses command-line and executes a command.
CoconaApp.Run(args);
}
// public method as a command ™
public void Hello(string name)
{
Console.WriteLine($"Hello {name}");
}
}
```
Class-based style (for .NET Standard / .NET 5)
```csharp
// This command accepts `--name ` and `--hey` options.
public void Hello(string name, bool hey) { ... }
```
Optional with default value (Class-based style)
If method parameters are [optional argument](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments#optional-arguments), Cocona treats those as optional command options. (That is, the parameters are treated as **required option** by default excepts boolean).
If a parameter is boolean, it's assumed that `false` default value is specified.
```csharp
// `--name "default user"` is specified implicity.
public void Hello(string name = "default user") { ... }
```
Class-based style (for .NET Standard / .NET 5))
```csharp
// The command accepts `-f` or `--force` option.
// Cocona's command-line parser accepts getopt-like styles. See below.
// $ remove --force --recursive
// $ remove -r -f
// $ remove -rf
public void Remove([Option('f')]bool force, [Option('r')]bool recursive) { ... }
```
Class-based style (for .NET Standard / .NET 5))
```csharp
// $ compile -I../path/to/foo.h -I/usr/include/bar.h -I/usr/include/baz.h nantoka.c
// include = new [] { "../path/to/foo.h", "/usr/include/bar.h", "/usr/include/baz.h" };
public void Compile([Option('I')]string[] include, [Argument]string file) { ... }
```
Class-based style (for .NET Standard / .NET 5))
```csharp
public void HasDescription([Option(Description = "Description of the option")] int value, [Argument(Description = "Description of the argument")]string arg) { ... }
```
Class-based style (for .NET Standard / .NET 5)
```csharp
// ./app alice karen
public void Hello([Argument]string from, [Argument]string to) { ... }
```
Class-based style (for .NET Standard / .NET 5)
```csharp
// ./copy file1 file2 file3 dest
public void Copy([Argument]string[] src, [Argument]string dest) { ... }
```
Class-based style (for .NET Standard / .NET 5)
If a command type has more than one public method or `[Command]`, those commands are exposed as sub-commands. You can implement an application that has sub-commands similar to `dotnet`, `git`, `kubectl` etc...
```csharp
static void Main(string[] args)
{
CoconaApp.Run(args);
}
[Command(Description = "Say hello")]
public void Hello([Argument]string name)
{
Console.WriteLine($"Hello {name}!");
}
[Command(Description = "Say goodbye")]
public void Bye([Argument]string name)
{
Console.WriteLine($"Goodbye {name}!");
}
```
Class-based style (for .NET Standard / .NET 5)
Cocona also supports nested sub-commands. Specify the class that has nested sub-commands using `HasSubCommands` attribute.
```csharp
[HasSubCommands(typeof(Server), Description = "Server commands")]
[HasSubCommands(typeof(Client), Description = "Client commands")]
class Program
{
static void Main(string[] args) => CoconaApp.Run(args);
// ./myapp info
public void Info() => Console.WriteLine("Show information");
}
// ./myapp server [command]
class Server
{
public void Start() => Console.WriteLine("Start");
public void Stop() => Console.WriteLine("Stop");
}
// ./myapp client [command]
class Client
{
public void Connect() => Console.WriteLine("Connect");
public void Disconnect() => Console.WriteLine("Disconnect");
}
```
Class-based style (for .NET Standard / .NET 5)
```csharp
[PrimaryCommand]
public void Primary(bool foo, string bar) { ... }
[Command]
public void Hello() { ... }
[Command]
public void Goodbye() { ... }
```
Class-based style (for .NET Standard / .NET 5)
```csharp
[OptionLikeCommand("hello", new[] {'f'}, typeof(Program), nameof(Hello))]
public void Execute()
=> Console.WriteLine("Execute");
private void Hello([Argument]string name)
=> Console.WriteLine($"Hello {name}!");
```
Class-based style (for .NET Standard / .NET 5)
```csharp
class Program : CoconaConsoleAppBase
{
...
public async Task RunAsync()
{
while (!Context.CancellationToken.IsCancellationRequested)
{
await Task.Delay(100);
}
}
}
```
Alternatively, you can use `ICoconaAppContextAccessor` and `CoconaAppContext` to access `CancellationToken`.
```csharp
public async Task RunAsync([FromService]ICoconaAppContextAccessor contextAccessor)
{
var ctx = contextAccessor.Current ?? throw new InvalidOperationException();
while (!ctx.CancellationToken.IsCancellationRequested)
{
await Task.Delay(100);
}
}
```
Class-based style (for .NET Standard / .NET 5)
```csharp
class Program
{
static void Main(string[] args)
{
CoconaApp.Run(args);
}
[SampleCommandFilter]
public void Hello()
{
Console.WriteLine($"Hello Konnichiwa");
}
}
class SampleCommandFilterAttribute : CommandFilterAttribute
{
public override async ValueTask OnCommandExecutionAsync(CoconaCommandExecutingContext ctx, CommandExecutionDelegate next)
{
Console.WriteLine($"Before Command: {ctx.Command.Name}");
try
{
return await next(ctx);
}
finally
{
Console.WriteLine($"End Command: {ctx.Command.Name}");
}
}
}
```
Class-based style (for .NET Standard / .NET 5)
If a constructor has parameters, Cocona injects an instance obtained from IServiceProvider into the parameter. Cocona will also inject an instance into the parameter if a command method parameter is marked as `[FromService]`.
```csharp
class Program
{
public Program(ILogger logger)
{
logger.LogInformation("Create Instance");
}
static void Main(string[] args)
{
CoconaApp.Create()
.ConfigureServices(services =>
{
services.AddTransient();
})
.Run(args);
}
public void Hello([FromService]MyService myService)
{
myService.Hello("Hello Konnichiwa!");
}
}
class MyService
{
private readonly ILogger _logger;
public MyService(ILogger logger)
{
_logger = logger;
}
public void Hello(string message)
{
_logger.LogInformation(message);
}
}
```
Class-based style (for .NET Standard / .NET 5)
```csharp
class Program : CoconaConsoleAppBase
{
static void Main(string[] args)
{
CoconaApp.Create()
.ConfigureLogging(logging =>
{
logging.AddDebug();
})
.Run(args);
}
public async Task RunAsync()
{
Context.Logger.LogInformation("Hello Konnichiwa!");
}
}
```