https://github.com/darkxahtep/darkxahtep.commandline
Allows creating CommandLine applications using Microsoft.Extensions.CommandLineUtils together with DI, Configuration and Logging in a convenient way similar to AspNetCore Hosting
https://github.com/darkxahtep/darkxahtep.commandline
aspnetcore cmd commandline configuration console console-application dependency-injection hosting logging microsoft-commandlineutils parser
Last synced: about 2 months ago
JSON representation
Allows creating CommandLine applications using Microsoft.Extensions.CommandLineUtils together with DI, Configuration and Logging in a convenient way similar to AspNetCore Hosting
- Host: GitHub
- URL: https://github.com/darkxahtep/darkxahtep.commandline
- Owner: DarkXaHTeP
- License: mit
- Created: 2017-10-27T00:18:13.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-12-09T00:46:25.000Z (over 7 years ago)
- Last Synced: 2025-05-07T06:06:24.056Z (about 2 months ago)
- Topics: aspnetcore, cmd, commandline, configuration, console, console-application, dependency-injection, hosting, logging, microsoft-commandlineutils, parser
- Language: C#
- Homepage:
- Size: 52.7 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# DarkXaHTeP.CommandLine
Allows creating CommandLine applications using Microsoft.Extensions.CommandLineUtils together with DI, Configuration and Logging in a convenient way similar to AspNetCore Hosting.
#### NuGet
[](https://www.nuget.org/packages/DarkXaHTeP.CommandLine/)
[](https://www.nuget.org/packages/DarkXaHTeP.CommandLine/)
#### Build
[](https://travis-ci.org/DarkXaHTeP/DarkXaHTeP.CommandLine)
[](https://coveralls.io/github/DarkXaHTeP/DarkXaHTeP.CommandLine)
## Getting Started
To use the library you need to go through 2 simple steps:
Define Startup class similar to Asp.Net Core:
```c#
public class Startup
{
public void Configure(IApplicationBuilder app)
{
app.OnExecute(async () =>
{
Console.WriteLine("Hello World")
return 0;
});
}
}
```
Create CommandLine Host using CommandLineHostBuilder and run it:
```c#
static class Program
{
static int Main(string[] args)
{
ICommandLineHost host = new CommandLineHostBuilder()
.UseStartup()
.Build();
return host.Run(args);
}
}
```
The application will print "Hello World" to console output and exit with 0 code.
## Release notes
For release notes please see [CHANGELOG.md](https://github.com/DarkXaHTeP/DarkXaHTeP.CommandLine/blob/master/CHANGELOG.md)
## Startup class
Same as Asp.Net Core Startup, CommandLine Startup can have two methods:
`void Configure(IApplicationBuilder app)` is required. This is where application
arguments and commands configuration happens using IApplicationBuilder.
`void ConfigureServices(IServiceCollection services)` is optional. Allows configuring Dependency Injection
by providing access to application's IServiceCollection. This method is invoked prior to `Configure`
## IApplicationBuilder interface
This interface provides a set of methods for configuring application. These methods are similar to provided by
Microsoft.Extensions.CommandLineUtils (actually this library uses CommandLineUtils internally,
however this may change in future due to the fact that CommandLineUtils is no longer supported).
```c#
IServiceProvider ApplicationServices { get; }
```
gives access to services registered in application
```c#
IApplicationBuilder Parent { get; }
```
contains link to parent IApplicationBuilder. Is null for the root builder
```c#
CommandArgument Argument(string name, string description, bool multipleValues = false);
```
allows to define command argument
```c#
IApplicationBuilder Command (string name, Action configure, bool throwOnUnexpectedArg = true);
```
allows to define command
```c#
void OnExecute (Func> invoke);
void OnExecute (Func invoke);
```
allows to define root or command execution callback
```c#
CommandOption Option (string template, string description, CommandOptionType optionType);
```
allows to define option
```c#
void ShowHelp (string commandName = null);
```
shows help for the particular command or a whole app. Could be used in execute callbacks
#### Example:
```c#
var greeter = app.ApplicationServices.GetRequiredService();
app.OnExecute(() => {
app.ShowHelp();
return 0;
});
app.Command("greet", command => {
var casualOption = command.Option("-c|--casual", "This greeting is informal/casual", CommandOptionType.NoValue);
var nameArgument = command.Argument("", "Names of persons to greet separated with space", true);
command.OnExecute(async () => {
string names = nameArgument.Values;
bool isCasual = casualOption.HasValue();
string greeting = await greeter.GetGreetingAsync(isCasual);
greeter.GreetAll(greeting, names);
return 0;
});
});
```
## CommandLineHostBuilder class
This class is similar to `WebHostBuilder` from Asp.Net Core and allows to setup application configuration,
logging and arguments parsing strategy before execution.
```c#
ICommandLineHostBuilder ConfigureAppConfiguration(Action configureDelegate);
ICommandLineHostBuilder ConfigureAppConfiguration(Action configureDelegate);
```
allows to configure application configuration
```c#
ICommandLineHostBuilder ConfigureLogging(Action configureLogging);
ICommandLineHostBuilder ConfigureLogging(Action configureLogging);
```
allows to configure logging
```c#
ICommandLineHostBuilder UseContentRoot(string contentRoot);
```
allows to redefine content root that will be used for resolving relative paths (e.g. path to json configuration file if used)
```c#
ICommandLineHostBuilder UseStartup() where TStartup : class;
```
sets Startup class to use. This method is required to call because no automatic Startup discovery is implemented
```c#
ICommandLineHostBuilder AllowUnexpectedArgs();
```
changes argument parsing to be less strict and not throw on unexpected arguments
```c#
ICommandLineHost Build();
```
builds command line host
```c#
ICommandLineHostBuilder ConfigureServices(Action configureServices);
ICommandLineHostBuilder ConfigureServices(Action configureServices);
```
allows to define additional services. Could be used in extension methods to extend behaviour
#### Example:
```c#
static class Program
{
static int Main(string[] args)
{
ICommandLineHost host = new CommandLineHostBuilder()
.UseContentRoot(Directory.GetCurrentDirectory())
.ConfigureLogging(logging =>
{
logging
.AddConsole()
.AddDebug();
})
.ConfigureAppConfiguration(config =>
{
config
.AddJsonFile("appsettings.json")
.AddConsul("application")
.AddEnvironmentVariables();
})
.UseStartup()
.AllowUnexpectedArgs()
.Build();
return host.Run(args);
}
}
```
## Dependency Injection
It is possible to inject dependencies either through constructor of `Startup` class or `Configure` method,
however only built-in dependencies (`IConfiguration`, `ICommandLineEnvironment`, `ILogger<>` etc.) are available through constructor
because `ConfigureServices` method is not yet called.
#### Example:
```c#
public class Startup
{
public Startup(
IConfiguration config,
ICommandLineEnvironment environment,
ILogger logger
)
{}
public void Configure(IApplicationBuilder app, IMyService service)
{
}
public void ConfigureServices(IServiceCollection services)
{
services.AddSingleton();
}
}
```
## Acknowledgements
This library is highly inspired by [AspNet.Core Hosting](https://github.com/aspnet/Hosting/tree/rel/2.0.0) from Microsoft
## Contribution
Feel free to ask questions and post bugs/ideas in the issues, as well as send pull requests.
[](https://github.com/DarkXaHTeP/DarkXaHTeP.CommandLine/blob/master/LICENSE)