CSF.NET.Spectre 1.4.1

🏗️ CSF.NET - Command Standardization Framework for .NET

CSF is an attribute based framework that makes creating and processing text based commands easy for any platform. It implements a modular, easy to implement pipeline for registering and executing commands, as well as a large number of extensions to make development on different platforms as easy as possible.

📍 Features

🗨️ Automated parameter parsing:

ValueType and nullable variant types are automatically parsed by the library and populate commands as below:

[Command("handle")]
public IResult Handle(int param1, DateTime param2)
{
    return Respond("{0}, {1}", param1, param2);
}

This will automatically parse int by using the default int.TryParse implementation, and will do the same for the DateTime.

Outside of this, implementing and adding your own TypeReader's is also supported to handle implementing commands with your own types. Nullability is automatically resolved by the library.

🧾 Parameterized remainder:

RemainderAttribute defines that all remaining parameters should be concatenated into a single 'remaining' string. This ensures that you don't need to add quotation marks for longer strings such as providing reasons, passwords or directories:

[Command("handle")]
public void Handle([Remainder] string path)
{
    if (!Path.Exists(path))
        Error("Failed to find specified path!");
}

🛑 Command preconditions.

Inheriting PreconditionAttribute creates a new precondition to add in the attribute range above commands. When a command is tried to be executed, it will walk through every added precondition and abort execution if any of them fail.

[RequireSystem(PlatformID.Unix)]
[Command("copy")]
public async Task Handle()
{
    
}

📖 Exposed command info & responsive errors:

CSF.NET will return results for building the command map and executing commands. If you want to run your commands asynchronously, you will have to handle the result process differently:

_csf.CommandExecuted += async (context, result) => 
{
    await Task.CompletedTask;
    if (result.IsSuccess)
        return;
    // handle failure.
}

🔗 Virtual base class to support freely overriding all results:

Every single method inside the CommandFramework is virtual and can be overwritten if desired to change results or rewrite certain steps inside the pipeline.

💡 Support for overriding context, module & framework:

IContext can be implemented in your own way, as it by itself serves as just a parsing tool. You can add a number of application-unique properties that are populated at creation. Because of how context's are created, it is easy to implement your own constructors and populate values from your own codebase.

💉 Dependency injection:

You can provide an IServiceProvider at execution to inject modules with dependencies. Modules are transient and will re-inject the expected services into the module every time a command is executed. Nullable services will not populate if the constructor parameter is declared as nullable.

🗺️ Roadmap

• Add complex parameters.

🤖 Samples

Samples are available to learn how to implement CSF in your own programs.

• CSF.Samples.Hosting
  • Shows how to implement CSF in an IHost design console application.
• CSF.Samples.Console
  • Shows how to implement CSF on a basic console application.
• CSF.Samples.TShock4
  • Shows how to implement CSF.NET.TShock into an OTAPI2 TShock plugin.
• CSF.Samples.TShock5
  • Shows how to implement CSF.NET.TShock into an OTAPI3 TShock plugin.

📰 Extensions

CSF introduces a number of extensions for external libraries.

• CSF.Hosting
  • A package that wraps around Microsoft.Extensions.Hosting.
• CSF.Spectre
  • A package that wraps around Spectre.Console.
• CSF.TShock
  • A package that wraps around TShock for Terraria.

❓ Explaining the internals:

CSF.NET works by grabbing all available modules on the specified assembly, storing them into a command map, and running through the pipeline to enter and execute the target command method.

🏭 Build steps:

Building the command map is done in a number of steps to ensure the pipeline can run through it succesfully.

• Find all types in the provided assembly and check if they inherit ModuleBase<>.
• Find all methods signed with CommandAttribute, if any.
• Create a new Module from the found module, and create a new Command for each command within.
• Populate the information with all found TypeReaders, PreconditionAttributes, attributes and aliases.
• Add all aliases for the command to the commandmap, sharing a reference to the same target command.

The entire build process resides here.

🔗 Pipeline steps:

The pipeline runs through several steps, in order, to make sure your command can safely pass through to its executing method.

• Look up all available commands matching the provided name.
• Find the best command match for the amount of provided parameters.
• Check all PreconditionAttributes to see if any fail.
• Construct the module and inject found services from the provided IServiceProvider
• Iterate through the parameters with provided TypeReaders and create a range of parsed parameters from the result.
• Run the BeforeExecuteAsync method.
• Run the command method.
• Run the AfterExecuteAsync method.
• Return a result to the caller.

The entire pipeline process resides here.