{"id":18756935,"url":"https://github.com/aiursoftweb/commandframework","last_synced_at":"2025-04-13T02:05:27.558Z","repository":{"id":186388308,"uuid":"670141109","full_name":"AiursoftWeb/CommandFramework","owner":"AiursoftWeb","description":"A command-line application development framework. Mirror of https://gitlab.aiursoft.cn/aiursoft/CommandFramework","archived":false,"fork":false,"pushed_at":"2024-09-12T07:00:43.000Z","size":519,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-09-12T16:50:54.791Z","etag":null,"topics":["cli","command-line","framework"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AiursoftWeb.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-24T11:38:19.000Z","updated_at":"2024-09-12T07:00:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"39808fc8-a0ba-483e-ab71-af0dbe908c91","html_url":"https://github.com/AiursoftWeb/CommandFramework","commit_stats":null,"previous_names":["aiursoftweb/commandframework"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiursoftWeb%2FCommandFramework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiursoftWeb%2FCommandFramework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiursoftWeb%2FCommandFramework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AiursoftWeb%2FCommandFramework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AiursoftWeb","download_url":"https://codeload.github.com/AiursoftWeb/CommandFramework/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223560672,"owners_count":17165505,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","framework"],"created_at":"2024-11-07T17:38:47.343Z","updated_at":"2024-11-07T17:38:48.076Z","avatar_url":"https://github.com/AiursoftWeb.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aiursoft CommandFramework\n\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.aiursoft.cn/aiursoft/commandframework/-/blob/master/LICENSE)\n[![Pipeline stat](https://gitlab.aiursoft.cn/aiursoft/commandframework/badges/master/pipeline.svg)](https://gitlab.aiursoft.cn/aiursoft/commandframework/-/pipelines)\n[![Test Coverage](https://gitlab.aiursoft.cn/aiursoft/commandframework/badges/master/coverage.svg)](https://gitlab.aiursoft.cn/aiursoft/commandframework/-/pipelines)\n[![NuGet version (Aiursoft.CommandFramework)](https://img.shields.io/nuget/v/Aiursoft.CommandFramework.svg)](https://www.nuget.org/packages/Aiursoft.CommandFramework/)\n[![ManHours](https://manhours.aiursoft.cn/r/gitlab.aiursoft.cn/aiursoft/commandframework.svg)](https://gitlab.aiursoft.cn/aiursoft/commandframework/-/commits/master?ref_type=heads)\n\nAiursoft CommandFramework is a framework for building command line tools.\n\n* Auto argument parsing\n* Auto help page generation\n* Auto version page generation\n* Run as service\n* Auto dependency injection\n* Auto command completion\n* Auto logger with `--verbose` option support\n* Run as a single command app or a nested command app\n\nWith this framework, you can build a modern command line tool with just a few lines of code.\n\n```bash\nC:\\workspace\u003e ninja.exe\n\nDescription:\n  Nuget Ninja, a tool for detecting dependencies of .NET projects.\n\nUsage:\n  Microsoft.NugetNinja [command] [options]\n\nOptions:\n  -p, --path \u003cpath\u003e (REQUIRED)   Path of the projects to be changed.\n  --nuget-server \u003cnuget-server\u003e  If you want to use a customized nuget server instead of the official nuget.org, \n  --token \u003ctoken\u003e                The PAT token which has privilege to access the nuget server.\n  -d, --dry-run                  Preview changes without actually making them\n  -v, --verbose                  Show detailed log\n  -?, -h, --help                 Show help and usage information\n\nCommands:\n  all, all-officials  The command to run all officially supported features.\n  remove-deprecated   The command to replace all deprecated packages to new packages.\n  upgrade-pkg         The command to upgrade all package references to possible latest and avoid conflicts.\n  clean-pkg           The command to clean up possible useless package references.\n  clean-prj           The command to clean up possible useless project references.\n  ```\n\n## Why this project?\n\nCommand-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.\n\n## How to install\n\nRun the following command to install `Aiursoft.CommandFramework` to your project from [nuget.org](https://www.nuget.org/packages/Aiursoft.CommandFramework/):\n\n```bash\ndotnet add package Aiursoft.CommandFramework\n```\n\n## Learn step 1: How to build an executable command handler?\n\nIn `Aiursoft.CommandFramework`, a command handler is a class that can be executed as a command.\n\nTo build an executable command, you can do:\n\n```csharp\nusing System.CommandLine;\nusing System.CommandLine.Invocation;\nusing Aiursoft.CommandFramework;\nusing Aiursoft.CommandFramework.Framework;\n\npublic class DownloadHandler : ExecutableCommandHandlerBuilder\n{\n    public static readonly Option\u003cstring\u003e Url =\n        new(\n            aliases: new[] { \"-u\", \"--url\" },\n            description: \"The target url to download.\")\n    {\n        IsRequired = true\n    };\n\n    protected override string Name =\u003e \"download\";\n\n    protected override string Description =\u003e \"Download an HTTP Url.\";\n    \n    protected override Option[] GetCommandOptions() =\u003e new Option[]\n    {\n        // Configure your options here.\n        DownloadHandler.Url\n    };\n\n    protected override Task Execute(InvocationContext context)\n    {\n        // Your code entry:\n        var url = context.ParseResult.GetValueForOption(DownloadHandler.Url);\n\n        Console.WriteLine($\"Downloading file from: {url}...\");\n\n        return Task.CompletedTask;\n    }\n}\n\n// Now you can start your app! Finish your `Program.cs` entry code!\npublic class Program\n{\n    public static async Task\u003cint\u003e Main(string[] args)\n    {\n        return await new SingleCommandApp\u003cDownloadHandler\u003e()\n            .WithDefaultOption(DownloadHandler.Url)\n            .RunAsync(args);\n    }\n}\n```\n\nBuild and run you app!\n\n```bash\n$ your-downloader.exe --url https://www.aiursoft.cn\n# outputs:\nDownloading file from: https://www.aiursoft.cn...\n```\n\n## Learn step 2: How to test your command handler?\n\nIt it super simple to test a command handler.\n\nAssuming you are using `Microsoft.VisualStudio.TestTools.UnitTesting`, you can do:\n\n```csharp\nusing Aiursoft.CommandFramework;\nusing Microsoft.VisualStudio.TestTools.UnitTesting;\n\n[TestClass]\npublic class IntegrationTests\n{\n    private readonly SingleCommandApp\u003cDownloadHandler\u003e _program = new SingleCommandApp\u003cDownloadHandler\u003e()\n            .WithDefaultOption(DownloadHandler.Url);\n\n    [TestMethod]\n    public async Task InvokeHelp()\n    {\n        var result = await _program.TestRunAsync(new[] { \"--help\" });\n        Assert.AreEqual(0, result.ProgramReturn);\n    }\n\n    [TestMethod]\n    public async Task InvokeVersion()\n    {\n        var result = await _program.TestRunAsync(new[] { \"--version\" });\n        Assert.AreEqual(0, result.ProgramReturn);\n    }\n\n    [TestMethod]\n    public async Task InvokeUnknown()\n    {\n        var result = await _program.TestRunAsync(new[] { \"--wtf\" });\n        Assert.AreEqual(1, result.ProgramReturn);\n    }\n}\n```\n\nNow write you UT, you can follow this practice:\n\n* Prepare some environment\n* Run your command handler\n* Assert the result\n* Clean up the environment\n\n## Learn step 3: Understand single command app and nested command app\n\nIn the previous steps, we have learned how to build a single command app. A single command app is a command line tool that only has one command.\n\nThis is useful for something with limited function, like:\n\n* Ping tool\n* File download tool\n* Web server tool\n\nBut in more scenarios, we usually need a command line tool with multiple commands. For example, `git` has many commands like `git clone`, `git commit`, `git push`, etc.\n\nA nested command app is a command line tool that has multiple commands. like:\n\n* [Nuget Ninja](https://gitlab.aiursoft.cn/aiursoft/nugetninja)\n\n## Learn step 4: How to build a nested command app?\n\nTo do that, first you need to build several executable command handlers. And then wrap them with a `NavigationCommandHandlerBuilder`:\n\n```csharp\npublic class NetworkHandler : NavigationCommandHandlerBuilder\n{\n    protected override string Name =\u003e \"network\";\n\n    protected override string Description =\u003e \"Network related commands.\";\n\n    protected override CommandHandlerBuilder[] GetSubCommandHandlers()\n    {\n        return\n        [\n            // Where the `DownloadHandler` is an executable command handler.\n            new DownloadHandler()\n        ];\n    }\n}\n```\n\nAnd it's very similar to build a nested command app:\n\n```csharp\n// Program.cs of the nested command app.\nreturn await new NestedCommandApp()\n    .WithGlobalOptions(CommonOptionsProvider.DryRunOption)\n    .WithGlobalOptions(CommonOptionsProvider.VerboseOption)\n    .WithFeature(new ConfigHandler())\n    .RunAsync(args);\n```\n\nNow you can try:\n\n```bash\nyour-app network download --url https://www.aiursoft.cn\n```\n\n## Learn step 5: How to build a command app with dependency injection?\n\nIt's easy to build a command app with dependency injection.\n\nOf course, you need to register your services in your `Startup` class first:\n\n```csharp\nusing Aiursoft.CommandFramework.Abstracts;\nusing Microsoft.Extensions.DependencyInjection;\n\nnamespace Aiursoft.DotDownload.Http;\n\npublic class Startup : IStartUp\n{\n    public void ConfigureServices(IServiceCollection services)\n    {\n        services.AddHttpClient(nameof(Downloader)).ConfigurePrimaryHttpMessageHandler(() =\u003e \n        {\n            return new HttpClientHandler()\n            {\n                AllowAutoRedirect = true,\n            };\n        });\n        services.AddTransient\u003cDownloader\u003e();\n    }\n}\n```\n\nThen in your `Execute(InvocationContext context)` function:\n\n```csharp\n// This code is inside an `ExecutableCommandHandlerBuilder`.\n\nprotected override async Task Execute(InvocationContext context)\n{\n  var verbose = context.ParseResult.GetValueForOption(CommonOptionsProvider.VerboseOption);\n  var host = ServiceBuilder\n            .CreateCommandHostBuilder\u003cStartup\u003e(verbose) // Your own startup class.\n            .Build();\n\n  var downloader = host.Services.GetRequiredService\u003cDownloader\u003e(); // Get a service from dependency injection\n  await downloader.DownloadWithWatchAsync(url, savePath, blockSize, threads, showProgressBar: !verbose);\n}\n```\n\nThat's it!\n\n## Learn step 6: How to build and configure a background service?\n\nYou can even start a background service in your command line tool!\n\nTo build a background service, you need to implement an `IHostedService`. Here use `ServerMonitor` as an example:\n\n```csharp\n\npublic class Startup : IStartUp\n{\n    public void ConfigureServices(IServiceCollection services)\n    {\n        services.AddTransient\u003cServerInitializer\u003e();\n        services.AddSingleton\u003cIHostedService, ServerMonitor\u003e();\n    }\n}\n\n// In your `ExecutableCommandHandlerBuilder`:\nprotected override async Task Execute(InvocationContext context)\n{\n    var verbose = context.ParseResult.GetValueForOption(CommonOptionsProvider.VerboseOption);\n    var profile = context.ParseResult.GetValueForOption(_profile);\n    \n    var host = ServiceBuilder\n        .CreateCommandHostBuilder\u003cStartup\u003e(verbose)\n        .ConfigureServices((hostBuilderContext, services)=\u003e\n        {\n            // You can configure your services here.\n            services.Configure\u003cProfileConfig\u003e(config =\u003e\n            {\n                config.Profile = profile;\n            });\n        })\n        .Build();\n\n    await host.StartAsync(); // Now your background service is running!\n    await host.WaitForShutdownAsync();\n}\n```\n\nTo read more about how to write an `IHostedService`, please read [this doc](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/hosted-services) from Microsoft.\n\n## Learn step 7: How to display a progress bar?\n\nIt's simple. You can use the `ProgressBar` class from `Aiursoft.CommandFramework`:\n\n```csharp\nusing Aiursoft.CommandFramework.Models;\n\nProgressBar? bar = null;\nif (showProgress) bar = new ProgressBar();\nvar completedTasks = 0;\nvar totalTasks = tasks.Length;\n\nforeach (var task in tasks)\n{\n    if (showProgress)\n    {\n        Interlocked.Increment(ref completedTasks);\n        // ReSharper disable once AccessToDisposedClosure\n        bar?.Report((double)completedTasks / totalTasks);\n    }\n}\nbar?.Dispose();\n```\n\nThat's it! When running, you may see:\n\n```bash\n[########################-----------------------]  50%\n```\n\n## Learn step 8: Read more examples\n\nIf you want to explore a real project built with this framework, please download the following project:\n\nSingle command app:\n\n* [Parser](https://gitlab.aiursoft.cn/anduin/parser) as an example.\n* [DotDownload](https://gitlab.aiursoft.cn/aiursoft/dotdownload) as an example.\n* [Httping](https://gitlab.aiursoft.cn/aiursoft/httping) as an example.\n* [Static](https://gitlab.aiursoft.cn/aiursoft/static) as an example.\n* [Dotlang](https://gitlab.aiursoft.cn/aiursoft/dotlang) as an example.\n\nNested command app:\n\n* [NiBot](https://gitlab.aiursoft.cn/aiursoft/nibot) as an example.\n* [Nuget Ninja](https://gitlab.aiursoft.cn/aiursoft/nugetninja) as an example.\n* [Happy Recorder](https://gitlab.aiursoft.cn/anduin/HappyRecorder) as an example.\n\nBackground service:\n\n* [IPMI Controller](https://gitlab.aiursoft.cn/aiursoft/ipmicontroller) as an example.\n\n## How to contribute\n\nThere are many ways to contribute to the project: logging bugs, submitting pull requests, reporting issues, and creating suggestions.\n\nEven 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.\n\nWe'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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiursoftweb%2Fcommandframework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faiursoftweb%2Fcommandframework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faiursoftweb%2Fcommandframework/lists"}