Aiursoft.CommandFramework
7.0.8
See the version list below for details.
dotnet add package Aiursoft.CommandFramework --version 7.0.8
NuGet\Install-Package Aiursoft.CommandFramework -Version 7.0.8
<PackageReference Include="Aiursoft.CommandFramework" Version="7.0.8" />
paket add Aiursoft.CommandFramework --version 7.0.8
#r "nuget: Aiursoft.CommandFramework, 7.0.8"
// Install Aiursoft.CommandFramework as a Cake Addin #addin nuget:?package=Aiursoft.CommandFramework&version=7.0.8 // Install Aiursoft.CommandFramework as a Cake Tool #tool nuget:?package=Aiursoft.CommandFramework&version=7.0.8
Aiursoft CommandFramework
Aiursoft CommandFramework is a framework for building command line tools.
- Auto argument parsing
- Auto help page generation
- Auto version page generation
With this framework, you can build a command line tool with just a few lines of code.
Example project it built:
C:\workspace> ninja.exe
Description:
Nuget Ninja, a tool for detecting dependencies of .NET projects.
Usage:
Microsoft.NugetNinja [command] [options]
Options:
-p, --path <path> (REQUIRED) Path of the projects to be changed.
--nuget-server <nuget-server> If you want to use a customized nuget server instead of the official nuget.org,
--token <token> The PAT token which has privilege to access the nuget server.
-d, --dry-run Preview changes without actually making them
-v, --verbose Show detailed log
-?, -h, --help Show help and usage information
Commands:
all, all-officials The command to run all officially supported features.
remove-deprecated The command to replace all deprecated packages to new packages.
upgrade-pkg The command to upgrade all package references to possible latest and avoid conflicts.
clean-pkg The command to clean up possible useless package references.
clean-prj The command to clean up possible useless project references.
Why this project?
Command-line applications are a great way to automate repetitive tasks or even to be your own productivity tool. But building a command-line application in .NET is not easy. You need to parse the arguments, generate help pages, and so on. This project is designed to help you build a command-line application with just a few lines of code.
Installation
Run the following command to install Aiursoft.CommandFramework
to your project from nuget.org:
dotnet add package Aiursoft.CommandFramework
Suggested project dependency tree (This will make your executable cli easy to be extended by plugins.):
stateDiagram-v2
YourProject.Executable.Cli --> YourProject.Plugin.A
YourProject.Executable.Cli --> YourProject.Plugin.B
YourProject.Executable.Cli --> YourProject.Plugin.C
YourProject.Plugin.A --> YourProject.Shared
YourProject.Plugin.B --> YourProject.Shared
YourProject.Plugin.C --> YourProject.Shared
YourProject.Shared --> Aiursoft.CommandFramework
First, write a simple class to provide options to your command:
using System.CommandLine;
using Aiursoft.CommandFramework.Models;
public static class OptionsProvider
{
public static RootCommand AddGlobalOptions(this RootCommand command)
{
var options = new Option[]
{
CommonOptionsProvider.DryRunOption,
CommonOptionsProvider.VerboseOption
};
foreach (var option in options)
{
command.AddGlobalOption(option);
}
return command;
}
}
In your YourProject.ExecutableCli
, write the program entry like this:
// Program.cs
using Aiursoft.CommandFramework;
using Aiursoft.CommandFramework.Extensions;
return await new AiursoftCommand()
.Configure(command =>
{
command
.AddGlobalOptions()
.AddPlugins(new CalendarPlugin());
})
.RunAsync(args);
Yes, I know you need to write plugins for your executable!
Now try to write a plugin:
using System.CommandLine;
using Aiursoft.CommandFramework.Abstracts;
using Aiursoft.CommandFramework.Framework;
using Aiursoft.CommandFramework.Models;
using Aiursoft.CommandFramework.Services;
using Microsoft.Extensions.DependencyInjection;
public class CalendarPlugin : IPlugin
{
public CommandHandler[] Install()
{
return new CommandHandler[]
{
new CalendarHandler(),
};
}
}
public class CalendarHandler : CommandHandler
{
public override string Name => "calendar";
public override string Description => "Show calendar.";
public override void OnCommandBuilt(Command command)
{
command.SetHandler(
Execute, CommonOptionsProvider.VerboseOption);
}
private async Task Execute(bool verbose)
{
var host = ServiceBuilder
.BuildHost<Startup>(verbose)
.Build();
await host.StartAsync();
var calendar = host.Services.GetRequiredService<CalendarRenderer>();
calendar.Render();
}
}
public class Startup : IStartUp
{
public void ConfigureServices(IServiceCollection services)
{
services.AddScoped<CalendarRenderer>();
}
}
public class CalendarRenderer
{
public void Render()
{
Console.WriteLine("Hello world!");
}
}
That's it!
$ yourapp calendar
Hello world!
Advanced Usage 1 - Nested Command Handler
Of course, handlers can be nested:
public class GetHandler : CommandHandler
{
public override string Name => "get";
public override string Description => "Get something.";
public override CommandHandler[] GetSubCommandHandlers()
{
return new CommandHandler[]
{
new DataHandler(),
new HistoryHandler(),
new CalendarHandler()
};
}
}
When your app starts, it just works!
$ yourapp get calendar
Hello world!
Advanced Usage 2 - More options
Of course, you can add more options to a specific command:
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using System.CommandLine;
using Aiursoft.CommandFramework.Framework;
using Aiursoft.CommandFramework.Services;
public class TranslateHandler : CommandHandler
{
private readonly Option<string> _bingApiKey = new(
aliases: new[] { "--key", "-k" },
description: "The Bing API Key.")
{
IsRequired = true
};
private readonly Option<string> _targetLang = new(
aliases: new[] { "--language", "-l" },
description: "The target language code. For example: zh, en, ja")
{
IsRequired = true
};
public override string Name => "translate";
public override string Description => "The command to start translation based on Bing Translate.";
public override Option[] GetCommandOptions()
{
return new Option[]
{
_bingApiKey,
_targetLang
};
}
public override void OnCommandBuilt(Command command)
{
command.SetHandler(
Execute,
OptionsProvider.PathOptions,
OptionsProvider.DryRunOption,
OptionsProvider.VerboseOption,
_bingApiKey,
_targetLang);
}
private Task Execute(string path, bool dryRun, bool verbose, string key, string targetLang)
{
var hostBuilder = ServiceBuilder.BuildHost<StartUp>(verbose);
hostBuilder.ConfigureServices(services =>
{
services.Configure<TranslateOptions>(options =>
{
options.BingApiKey = key;
options.TargetLang = targetLang;
});
});
var entry = hostBuilder
.Build()
.Services
.GetRequiredService<TranslateEntry>(); // TranslateEntry is a class that injects 'IOptions<TranslateOptions>'.
return entry.OnServiceStartedAsync(path, !dryRun);
}
}
Now you have more options to use:
$ yourapp translate --key AB123 --language zh-CN
Advanced Usage 3 - Write tests
If you want to write tests for your command line tool, you can use TestRunAsync
method to invoke your command:
using Aiursoft.CommandFramework;
using Aiursoft.CommandFramework.Extensions;
using Microsoft.VisualStudio.TestTools.UnitTesting;
[TestClass]
public class IntegrationTests
{
private readonly AiursoftCommand _program;
public IntegrationTests()
{
_program = new AiursoftCommand()
.Configure(command =>
{
command
.AddGlobalOptions()
.AddPlugins(
// Your plugins
);
});
}
[TestMethod]
public async Task InvokeHelp()
{
var result = await _program.TestRunAsync(new[] { "--help" });
Assert.AreEqual(0, result.ProgramReturn);
Assert.IsTrue(result.Output.Contains("Options:"));
Assert.IsTrue(string.IsNullOrWhiteSpace(result.Error));
}
[TestMethod]
public async Task InvokeVersion()
{
var result = await _program.TestRunAsync(new[] { "--version" });
Assert.AreEqual(0, result.ProgramReturn);
}
[TestMethod]
public async Task InvokeUnknown()
{
var result = await _program.TestRunAsync(new[] { "--wtf" });
Assert.AreEqual(1, result.ProgramReturn);
}
[TestMethod]
public async Task InvokeWithoutArg()
{
var result = await _program.TestRunAsync(Array.Empty<string>());
Assert.AreEqual(1, result.ProgramReturn);
}
}
Download a real sample project
If you want to explore a real project built with this framework, please check Parser as an example.
How to contribute
There are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.
Even if you with push rights on the repository, you should create a personal fork and create feature branches there when you need them. This keeps the main repository clean and your workflow cruft out of sight.
We're also interested in your feedback on the future of this project. You can submit a suggestion or feature request through the issue tracker. To make this process more effective, we're asking that these include more information to help define them more clearly.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net7.0 is compatible. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net7.0
- Microsoft.Extensions.Hosting (>= 7.0.1)
- System.CommandLine (>= 2.0.0-beta4.22272.1)
NuGet packages (3)
Showing the top 3 NuGet packages that depend on Aiursoft.CommandFramework:
Package | Downloads |
---|---|
Anduin.HappyRecorder.PluginFramework
Package Description |
|
Aiursoft.Dotlang.Core
Package Description |
|
Aiursoft.NiBot.Dedup
Nuget package of 'Dedup' provided by Aiursoft |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
8.0.6 | 62 | 10/9/2024 |
8.0.5 | 51 | 10/7/2024 |
8.0.4 | 55 | 7/9/2024 |
8.0.3 | 55 | 6/28/2024 |
8.0.2 | 60 | 6/27/2024 |
8.0.1 | 87 | 2/19/2024 |
8.0.0 | 65 | 2/19/2024 |
7.0.25 | 95 | 1/30/2024 |
7.0.24 | 151 | 12/12/2023 |
7.0.23 | 79 | 12/12/2023 |
7.0.22 | 70 | 12/12/2023 |
7.0.21 | 78 | 12/12/2023 |
7.0.20 | 82 | 12/11/2023 |
7.0.19 | 83 | 12/11/2023 |
7.0.18 | 77 | 12/11/2023 |
7.0.17 | 87 | 12/6/2023 |
7.0.16 | 84 | 12/6/2023 |
7.0.15 | 83 | 12/6/2023 |
7.0.14 | 79 | 12/6/2023 |
7.0.13 | 73 | 12/6/2023 |
7.0.12 | 78 | 12/6/2023 |
7.0.11 | 86 | 12/6/2023 |
7.0.10 | 86 | 12/6/2023 |
7.0.9 | 75 | 12/6/2023 |
7.0.8 | 86 | 12/6/2023 |
7.0.7 | 78 | 12/6/2023 |
7.0.6 | 105 | 11/11/2023 |
7.0.5 | 89 | 11/2/2023 |
7.0.4 | 74 | 11/2/2023 |
7.0.3 | 78 | 11/2/2023 |
7.0.2 | 96 | 9/13/2023 |
7.0.1 | 96 | 9/13/2023 |
7.0.0 | 90 | 9/5/2023 |
6.0.0 | 205 | 7/20/2023 |
1.0.0 | 132 | 7/20/2023 |