A module to "Decorate" a task with "Arguments"

[EdLichtman]

I've been working on this myself and have a pretty good foundation of code, with test coverage...

I'd like to call it "Sprinkles", which goes on top of "Frosting". It's a "Decorator" for Properties in a task. Basically, you add attributes to a property in a task, like TaskArgumentName, and TaskArgumentIsRequired, and it uses reflection to set the value by type (For instance you could make an Int32, and it will convert the string to an Int32, or throw a descriptive Argument Error suggesting that the Argument is not a valid value based on the type).

There is stuff I want to do but can't without incorporating it into the "internal" library structure of Frosting.

One of the things I envision is a new command line argument: "--arguments", where you can have a TaskArgumentDescription attribute, and when you type in --arguments --target=YourTask, it will say:
The following argument(s) are required:

• MyRequiredArgument (Boolean): This is an example of a required argument description.
  The following argument(s) are optional:
• MyOptionalArgument (ImmutableList): This is an example of how you could pass in multiple iterations of the same argument.

Another thought I had was whether or not it would accept deserialization of JSON strings or something -- but I think that's less important than the other stuff I mentioned.

What do you think? If you're one of the contributors that could approve of this, I would love to talk with you further, walk you through my code and changes and get any ideas for modification.

[EdLichtman]

So here's what it looks like in practice:

[TaskName("StartService")]
[TaskDescription("Starts a windows service.")]
public sealed class StartServiceTask : AsyncFrostingTask<BuildContext>
{
    [TaskArgumentName("service_name")]
    [TaskArgumentDescription("The name of the service to start.")]
    [TaskArgumentIsRequired]
    public String ServiceName { get; set; }

    [TaskArgumentName("depends_upon_service_names")]
    [TaskArgumentDescription("The name of any services this depends upon to start.")]
    public IList<String> RequiredServiceNames { get; set; }

    [TaskArgumentName("timeout_in_seconds")]
    [TaskArgumentDescription("The total number of seconds to wait before cancelling this task.")]
    public Int32 TimeoutInSeconds { get; set; }

    [TaskArgumentName("force")]
    [TaskArgumentDescription("Attempts to start it via elevated permissions.")]
    [TaskArgumentFlag]
    public Boolean Force { get; set; }

    private ServiceTaskRunner runner;

    public StartServiceTask(ServiceTaskRunner runner)
    {
        this.runner = runner;
    }

    public override async Task RunAsync(BuildContext context)
    {
        if (this.Force) 
            this.runner.ElevatePermissions()

        if (this.TimeoutInSeconds != default)
            //todo something to create a cancellation token or something
        await this.runner.StartServiceAsync(this.ServiceName, this.RequiredServiceNames);
    }
}

So in my example, I'm trying to abstract out actual deployment logic from the task itself so it can be well-tested. Therefore it looks a lot cleaner, plus when I'm missing any required arguments, it tells me ALL of the arguments I'm missing at once instead of waiting for me to mess up again, one by one.

[EdLichtman]

To add to this further, I've built a task with the documentation Builder that I'd like to incorporate into the final design.

This is the output of the above task:

========================================
Arguments
========================================
Task: StartService
Description: Starts a windows service.

The following properties are required:
 * service_name
   * Description: The name of the service to start.
   * Accepts: String

The following properties are optional:
 * depends_upon
   * Description: The name of any services this depends upon to start.
   * Accepts: String (argument can be provided multiple times)
 * timeout_in_seconds
   * Description: The total number of seconds to wait before cancelling this task.
   * Accepts: Int32
 * force
   * Description: Attempts to start it via elevated permissions.
   * Accepts: Boolean
   * Can be provided as a flag

[EdLichtman]

Also, I understand I can create my own external module, but because the CakeEngine and strategies are sealed, I'm having trouble figuring out how I can override the information that gets passed through the runner. I suppose I can override the DescriptionScriptHost, and it will describe differently?

[EdLichtman]

https://www.nuget.org/packages/Cake.Sprinkles.Module

It exists now. I'd like to add this to the core library so it doesn't have to take over the one tasksetup, and would like if someone could look at it and see if they agree it's good.