added publish GitHub workflow, core components documented

Author: hatelamers

.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+
+name: Publish Release
+
+on:
+  release:
+    types: [published]
+env:
+    PROJECT_NAME: CommandLineX
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: 8.0.x
+    # - name: Verify commit exists in origin/main
+    #   run: |
+    #     git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/*
+    #     git branch --remote --contains | grep origin/main
+    - name: Set VERSION variable from tag
+      shell: bash
+      run: echo "VERSION=${GITHUB_REF/refs\/tags\/v/}" >> $GITHUB_ENV
+
+    - name: Build
+      run: dotnet build -c Release /p:Version=${VERSION}
+    - name: Test
+      run: dotnet test -c Release /p:Version=${VERSION} --no-build
+    - name: Pack
+      run: dotnet pack -c Release /p:Version=${VERSION} --no-build --output .
+    - name: Push NuGet
+      run: dotnet nuget push "*.nupkg" -s https://api.nuget.org/v3/index.json -k ${NUGET_TOKEN} --skip-duplicate
+      env:
+        NUGET_TOKEN: ${{ secrets.NUGET_PUBLISH_TOKEN }}
+
+    - name: Publish Binaries to GitHub
+      uses: softprops/action-gh-release@v2
+      with:
+        files: "*.nupkg"
+      env:
+        GITHUB_TOKEN: ${{ secrets.PACKAGE_WRITE_TOKEN }}

CommandLineX.sln

@@ -13,6 +13,7 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "GitHub", "GitHub", "{8D85AE92-B925-47E0-9913-0CE8840E017C}"
 	ProjectSection(SolutionItems) = preProject
 		.github\workflows\dotnet.yml = .github\workflows\dotnet.yml
+		.github\workflows\publish.yml = .github\workflows\publish.yml
 	EndProjectSection
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CommandLineX", "src\CommandLineX\CommandLineX.csproj", "{66FE8D23-FD3C-45CB-8C71-D54E48AD39CA}"

README.md

@@ -20,7 +20,7 @@ In the directory of your project execute
 dotnet add package diVISION.CommandLineX
 ```
 
-### Integrating The Library
+### Integrating The Library In Your Application
 1. Create `MyFirstAction.cs` (command action model) in your project directory:
    ```cs
     using diVISION.CommandLineX;
@@ -29,11 +29,12 @@ dotnet add package diVISION.CommandLineX
     {
         public class MyFirstAction(ILogger<MyFirstAction> logger): ICommandAction
         {
+            // injected by the host via DI
             private readonly ILogger<MyFirstAction> _logger = logger;
 
-            // do-amount argument
+            // "do-amount" argument
             public IEnumerable<int> DoAmount { get; set; } = [0];
-            // --directory option
+            // "--directory" option
             public DirectoryInfo Directory { get; set; } = new (".");
 
             public int Invoke(CommandActionContext context)
@@ -66,6 +67,7 @@ dotnet add package diVISION.CommandLineX
         })
         .ConfigureDefaults(null)
         .UseConsoleLifetime()
+        // next 2 calls initalize CommandLine hosting
         .UseCommandLine(rootCmd)
         .UseCommandWithAction<MyFirstAction>(rootCmd, new("myFirst", "Doing things")
         {
@@ -112,4 +114,4 @@ dotnet build
 ```
 
 ## Contributing
-All contributions to development and error fixing are welcome. Please always use `develop` branch for forks and pull requests, `main` is reserved for stable releases and critical vulnarability fixes only. All code changes should meet minimal code coverage requirements to be merged into `main` or `develop`, the coverage requirements are: lines - 95%, branches - 95%, methods - 100%.
+All contributions to development and error fixing are welcome. Please always use `develop` branch for forks and pull requests, `main` is reserved for stable releases and critical vulnarability fixes only. Please note: all code changes should meet minimal code coverage requirements to be merged into `main` or `develop`.

src/CommandLineX/CommandActionContext.cs

@@ -7,9 +7,22 @@
 
 namespace diVISION.CommandLineX
 {
+    /// <summary>
+    /// Context information collected by the framwork during parsing of the command line arguments.
+    /// All bound command action models are passed this in the <c cref="ICommandAction.Invoke(CommandActionContext)">Invoke</c>
+    /// or resp. <c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">InvokeAsync</c> call.
+    /// </summary>
+    /// <param name="parseResult"></param>
+    /// <param name="unboundSymbols"></param>
     public class CommandActionContext(ParseResult parseResult, IEnumerable<Symbol> unboundSymbols)
     {
+        /// <summary>
+        /// Result of command line parsing.
+        /// </summary>
         public ParseResult ParseResult => parseResult;
+        /// <summary>
+        /// Collection of symbols that have been defined by the bound <c cref="Command">Command</c> but could not be resolved in the model.
+        /// </summary>
         public IEnumerable<Symbol> UnboundSymbols => unboundSymbols;
     }
 }

src/CommandLineX/CommandLineOptions.cs

@@ -7,6 +7,12 @@
 
 namespace diVISION.CommandLineX
 {
+    /// <summary>
+    /// Container with configuration options for <c cref="System.CommandLine">System.CommandLine</c>.
+    /// An instance of this class initialized with the defaults is passed to the configure action by
+    /// <c cref="diVISION.CommandLineX.Hosting.CommmandLineHostingExtension.UseCommandLine(Microsoft.Extensions.Hosting.IHostBuilder, RootCommand, Action{CommandLineOptions}?)">CommmandLineHostingExtension.UseCommandLine</c>,
+    /// the action then can modify the configuration as required.
+    /// </summary>
     public class CommandLineOptions
     {
         public ParserConfiguration? ParserConfiguration { get; set; }

src/CommandLineX/CommandLineX.csproj

@@ -5,7 +5,7 @@
     <TargetFramework>net8.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>0.1.0-rc01</Version>
+    <Version>0.1.0-rc02</Version>
 	<Description>Hosting and model binding extensions for System.CommandLine</Description>
   </PropertyGroup>
 

src/CommandLineX/Hosting/CommmandLineHostingExtension.cs

@@ -10,8 +10,21 @@
 
 namespace diVISION.CommandLineX.Hosting
 {
+    /// <summary>
+    /// <see cref="https://github.com/dotnet/command-line-api"><c>System.CommandLine</c></see> integration with <c>IHostBuilder</c> and <c>IHost</c>.
+    /// </summary>
     public static class CommmandLineHostingExtension
     {
+        /// <summary>
+        /// Registers basic services neccessary to invoke commands from within a host.
+        /// If <paramref name="configure"/> action is provided, it is called with <c>CommandLineOptions</c> instance
+        /// where configuration for <c>System.CommandLine</c> can be set up. Call this method before any other extension is used.
+        /// </summary>
+        /// <seealso cref="CommandLineOptions"/>
+        /// <param name="builder">host builder instance being extended</param>
+        /// <param name="rootCommand" cref="RootCommand">root command to be invoked by host</param>
+        /// <param name="configure">optional configure action</param>
+        /// <returns><paramref name="builder"/></returns>
         public static IHostBuilder UseCommandLine(this IHostBuilder builder, RootCommand rootCommand, Action<CommandLineOptions>? configure = null)
         {
             var registry = new CommandActionRegistry();
@@ -37,6 +50,13 @@ public static IHostBuilder UseCommandLine(this IHostBuilder builder, RootCommand
             return builder;
         }
 
+        /// <summary>
+        /// Registers <c cref="CommandLineInvocationContext">CommandLineInvocationContext</c> and <c cref="CommandLineHostedService">CommandLineHostedService</c>
+        /// so that commands specified by <paramref name="args"/> will be parsed and invoked asynchronously at the host startup.
+        /// </summary>
+        /// <param name="builder">host builder instance being extended</param>
+        /// <param name="args">command line arguments to parse</param>
+        /// <returns><paramref name="builder"/></returns>
         public static IHostBuilder UseHostedCommandInvocation(this IHostBuilder builder, string[] args)
         {
             builder.ConfigureServices(services =>
@@ -47,6 +67,19 @@ public static IHostBuilder UseHostedCommandInvocation(this IHostBuilder builder,
             return builder;
         }
 
+        /// <summary>
+        /// Adds specified <paramref name="command"/> to <paramref name="parent"/> command (ususally <c>RootCommand</c>) and binds <typeparamref name="TAction"/> model to the former.
+        /// Requires comand line services to be set up by <c cref="UseCommandLine(IHostBuilder, RootCommand, Action{CommandLineOptions}?)">UseCommandLine</c> prior to this call.
+        /// </summary>
+        /// <seealso cref="UseCommandLine(IHostBuilder, RootCommand, Action{CommandLineOptions}?)"/>
+        /// <typeparam name="TAction">action to bind</typeparam>
+        /// <param name="builder">host builder instance being extended</param>
+        /// <param name="parent">parent <c cref="Command">Command</c> to which <paramref name="command"/> will be added</param>
+        /// <param name="command"><c cref="Command">Command</c> used for binding</param>
+        /// <param name="runAsync">indicates whether <typeparamref name="TAction"/>.<c cref="ICommandAction.Invoke(CommandActionContext)">Invoke</c>
+        /// or <typeparamref name="TAction"/>.<c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">InvokeAsync</c> is used to execute the action</param>
+        /// <returns><paramref name="builder"/></returns>
+        /// <exception cref="InvalidOperationException"></exception>
         public static IHostBuilder UseCommandWithAction<TAction>(this IHostBuilder builder, Command parent, Command command, bool runAsync = true)
             where TAction : class, ICommandAction
         {
@@ -90,6 +123,14 @@ public static IHostBuilder UseCommandWithAction<TAction>(this IHostBuilder build
             return builder;
         }
 
+        /// <summary>
+        /// Starts the <paramref name="host"/>, parses command line <paramref name="args"/> and executes matching <c cref="ICommandAction.Invoke(CommandActionContext)">ICommandAction.Invoke</c>
+        /// previously bound by <c cref="UseCommandWithAction{TAction}(IHostBuilder, Command, Command, bool)">UseCommandWithAction</c>. If no match exists an error message is displayed and an error code is returned.
+        /// </summary>
+        /// <seealso cref="UseCommandWithAction{TAction}(IHostBuilder, Command, Command, bool)"/>
+        /// <param name="host">host instance being extended</param>
+        /// <param name="args">command line arguments to parse</param>
+        /// <returns>either result of <c cref="ICommandAction.Invoke(CommandActionContext)">ICommandAction.Invoke</c> or an error code</returns>
         public static int RunCommandLine(this IHost host, string[] args)
         {
             host.ThrowIfHostedCommandLine();
@@ -98,6 +139,15 @@ public static int RunCommandLine(this IHost host, string[] args)
             return invoker.Invoke(args);
         }
 
+        /// <summary>
+        /// Starts the <paramref name="host"/>, parses command line <paramref name="args"/> and executes matching <c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">ICommandAction.InvokeAsync</c>
+        /// previously bound by <c cref="UseCommandWithAction{TAction}(IHostBuilder, Command, Command, bool)">UseCommandWithAction</c>. If no match exists an error message is displayed and an error code is returned.
+        /// </summary>
+        /// <seealso cref="UseCommandWithAction{TAction}(IHostBuilder, Command, Command, bool)"/>
+        /// <param name="host">host instance being extended</param>
+        /// <param name="args">command line arguments to parse</param>
+        /// <param name="cancellationToken">cancellation token passed to <c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">ICommandAction.InvokeAsync</c></param>
+        /// <returns>either result of <c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">ICommandAction.InvokeAsync</c> or an error code</returns>
         public static async Task<int> RunCommandLineAsync(this IHost host, string[] args, CancellationToken cancellationToken = default)
         {
             host.ThrowIfHostedCommandLine();
@@ -106,6 +156,15 @@ public static async Task<int> RunCommandLineAsync(this IHost host, string[] args
             return await invoker.InvokeAsync(args, cancellationToken);
         }
 
+        /// <summary>
+        /// Starts the <paramref name="host"/>, during the startup the <c cref="CommandLineHostedService">CommandLineHostedService</c>
+        /// (registered by <c cref="UseHostedCommandInvocation(IHostBuilder, string[])">UseHostedCommandInvocation</c>)
+        /// parses the command line and executes matching <c cref="ICommandAction.Invoke(CommandActionContext)">ICommandAction.Invoke</c>
+        /// previously bound by <c cref="UseCommandWithAction{TAction}(IHostBuilder, Command, Command, bool)">UseCommandWithAction</c>. If no match exists an error message is displayed and an error code is returned.
+        /// </summary>
+        /// <seealso cref="UseHostedCommandInvocation(IHostBuilder, string[])"/>
+        /// <param name="host">host instance being extended</param>
+        /// <returns>either result of <c cref="ICommandAction.Invoke(CommandActionContext)">ICommandAction.Invoke</c> or an error code</returns>
         public static int RunCommandLineHosted(this IHost host)
         {
             host.CheckInvocationContext();
@@ -119,6 +178,16 @@ public static int RunCommandLineHosted(this IHost host)
             return Environment.ExitCode;
         }
 
+        /// <summary>
+        /// Starts the <paramref name="host"/>, during the startup the <c cref="CommandLineHostedService">CommandLineHostedService</c>
+        /// (registered by <c cref="UseHostedCommandInvocation(IHostBuilder, string[])">UseHostedCommandInvocation</c>)
+        /// parses the command line and executes matching <c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">ICommandAction.InvokeAsync</c>
+        /// previously bound by <c cref="UseCommandWithAction{TAction}(IHostBuilder, Command, Command, bool)">UseCommandWithAction</c>. If no match exists an error message is displayed and an error code is returned.
+        /// </summary>
+        /// <seealso cref="UseHostedCommandInvocation(IHostBuilder, string[])"/>
+        /// <param name="host">host instance being extended</param>
+        /// <param name="cancellationToken">cancellation token passed to the <paramref name="host"/></param>
+        /// <returns>either result of <c cref="ICommandAction.InvokeAsync(CommandActionContext, CancellationToken)">ICommandAction.InvokeAsync</c> or an error code</returns>
         public static async Task<int> RunCommandLineHostedAsync(this IHost host, CancellationToken cancellationToken = default)
         {
             host.CheckInvocationContext();
@@ -133,6 +202,11 @@ public static async Task<int> RunCommandLineHostedAsync(this IHost host, Cancell
             return Environment.ExitCode;
         }
 
+        /// <summary>
+        /// For internal use.
+        /// </summary>
+        /// <param name="host">host instance being extended</param>
+        /// <exception cref="InvalidOperationException"></exception>
         public static void CheckInvocationContext(this IHost host)
         {
             if (null == host.Services.GetService<CommandLineInvocationContext>())
@@ -141,6 +215,11 @@ public static void CheckInvocationContext(this IHost host)
             }
         }
 
+        /// <summary>
+        /// For internal use.
+        /// </summary>
+        /// <param name="host">host instance being extended</param>
+        /// <exception cref="InvalidOperationException"></exception>
         public static void ThrowIfHostedCommandLine(this IHost host)
         {
             if (host.Services.GetService<IHostedService>() is CommandLineHostedService)

src/CommandLineX/ICommandAction.cs

@@ -5,9 +5,26 @@
  **/
 namespace diVISION.CommandLineX
 {
+    /// <summary>
+    /// Interface for command action model binding.
+    /// </summary>
     public interface ICommandAction
     {
+        /// <summary>
+        /// Called by the framework when a synchronous action binding matches the command line arguments.
+        /// </summary>
+        /// <seealso cref="CommandActionContext"/>
+        /// <param name="context">current execution context</param>
+        /// <returns></returns>
         int Invoke(CommandActionContext context);
+
+        /// <summary>
+        /// Called by the framework when an asynchronous action binding matches the command line arguments.
+        /// </summary>
+        /// <seealso cref="CommandActionContext"/>
+        /// <param name="context">urrent execution context</param>
+        /// <param name="cancellationToken"></param>
+        /// <returns></returns>
         Task<int> InvokeAsync(CommandActionContext context, CancellationToken cancellationToken = default);
     }
 }

test/CommandLineX.Tests/CommandLineX.Tests.csproj

@@ -5,7 +5,7 @@
     <LangVersion>latest</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-	<Version>0.1.0-rc01</Version>
+	<Version>0.1.0-rc02</Version>
   </PropertyGroup>
 
 	<ItemGroup>