Isop is the swedish name for hyssop. Like any spice it is intended to give flavor to the development of command line apps.
C# Ruby Other
Switch branches/tags
Nothing to show
Latest commit 4da0c77 Feb 25, 2017 @wallymathieu committed on GitHub Note about using Swagger instead
Permalink
Failed to load latest commit information.
presentation
provisioning
src
.gitattributes
.gitignore
.travis.yml
Gemfile
Gemfile.lock
README.md
Vagrantfile
appveyor.yml
isop.sublime-project
license.txt
rakefile.rb

README.md

Isop Build Status Build status

The name

Isop is the swedish name for hyssop. Like any spice it is intended to give flavor to the development of command line apps in .net.

Goal

The goal is to be able to write code like:

someprogram.exe My Action --argument value

Or if you prefer:

someprogram.exe My Action /argument value

Isop will also figure out what you mean if you write with an equals sign between argument and value:

someprogram.exe My Action --argument=value

Or if you want to write it shorter you can skip the argument name:

someprogram.exe My Action value

So that the class with the name My or MyController and the method with the name Action gets invoked.

This library is intended to be like chocolate pudding mix. Not something that will replace your dinner, but rather something easy to make for dessert. A way of helping you build for instance the essential administrative apps. It's not a replacement for baking cake (building a full blown administrative interface in html, silverlight, wpf ... ).

When to use Isop

  • Early in your development life cycle (before having tools around for your business app)
  • You want an exe with many different commands organized into categories (here called controllers)

When not to use Isop

  • When your exe only has one command, then a simpler library like ndesc options is preferable.
  • You do not want any magic. Isop tries to help you with binding arguments to method arguments.
  • When you have a micro service solution together with IdentityServer so that you can use Swagger to fill the same role. Swashbuckle can be configured to use implicit auth flow.

License

MIT License

Nuget packages

Isop

Example

Having your own Main

You're hooking it up by writing something like:

static void Main(string[] args)
{
  new Build()
       .Recognize(typeof(CustomerController))
       .Parse(args)
       .Invoke(Console.Out);
}

Where your controller looks something like this:


public class MyController
{
    private readonly CustomerRepository _repository;
    public MyController()
    {
        _repository = new CustomerRepository();
    }
    public IEnumerable<string> Add(string name)
    { 
        yield return "Starting to insert customer";
        _repository.Insert( new Customer{ Name = name } );
        yield return "Customer inserted";  
    }
}

When invoked it will output two lines to the command prompt, the yielded lines above.

Using a configuration class for isop


class IsopConfiguration:IDisposable
{
...
    public IEnumerable Recognizes()
    {
        return new[] { typeof(CustomerController) };
    }
    public object ObjectFactory(Type type)
    {
        return _myIOC.Resolve(type);
    }
    public CultureInfo Culture
    {
        get{ return CultureInfo.GetCultureInfo("sv-SE"); }
    }
    public bool RecognizeHelp{get{return true;}}
    public void Dispose()
    {
        _myIOC.Dispose();
    }
}
class Program
{
    static void Main(string[] args)
    {
        var configuration = new IsopConfiguration();
        new Build()
          .Configuration(configuration)
          .Parse(args)
          .Invoke(Console.Out);
    }
}

This is equivalent to the following fluent configuration of isop:


class Program
{
    static void Main(string[] args)
    {
        new Build()
          .SetCulture(CultureInfo.GetCultureInfo("sv-SE"))
          .Recognize(typeof(CustomerController))
          .SetFactory(_myIOC.Resolve);
          .ShouldRecognizeHelp()
          .Parse(args)
          .Invoke(Console.Out);
    }
}

Handling errors and unrecognized parameters


class Program
{
    static void Main(string[] args)
    {
        var parserBuilder = new Build()
                  .SetCulture(CultureInfo.GetCultureInfo("sv-SE"))
                  .Recognize(typeof(CustomerController))
                  .SetFactory(_myIOC.Resolve);
                  .ShouldRecognizeHelp();
        try
        {
            var parsedMethod = parserBuilder.Parse(args);
            if (parsedMethod.UnRecognizedArguments.Any())//Warning:
            {
                var unRecognizedArgumentsMessage = string.Format(
@"Unrecognized arguments: 
{0}
Did you mean any of these arguments?
{1}", String.Join(",", parsedMethod.UnRecognizedArguments.Select(unrec => unrec.Value).ToArray()),
  String.Join(",", parsedMethod.ArgumentWithOptions.Select(rec => rec.Argument.ToString()).ToArray()));
                Console.WriteLine(unRecognizedArgumentsMessage);
            }else
            {
                parsedMethod.Invoke(Console.Out);
            }
        }
        catch (TypeConversionFailedException ex)
        {
            
             Console.WriteLine(String.Format("Could not convert argument {0} with value {1} to type {2}", 
                ex.Argument, ex.Value, ex.TargetType));
             if (null!=ex.InnerException)
            {
                Console.WriteLine("Inner exception: ");
                Console.WriteLine(ex.InnerException.Message);
            }
        }
        catch (MissingArgumentException ex)
        {
            Console.WriteLine(String.Format("Missing argument(s): {0}",String.Join(", ",ex.Arguments.Select(a=>String.Format("{0}: {1}",a.Key,a.Value)).ToArray())));
            
            Console.WriteLine(parserBuilder.Help());
        }

    }
}

Why all this code? Mostly it's because I want the programmer to be able to have as much freedom as possible to handle errors and show error messages as he/she sees fit.

Using Isop.cli.exe

You're hooking it up by writing something like:

 class IsopConfiguration
{
    public IEnumerable Recognizes()
    {
        return new[] { typeof(CustomerController) };
    }
    public string Global {
        get;
        set;
    }
    [Required]
    public string GlobalRequired
    {
        get;
        set;
    }
    public object ObjectFactory(Type type)
    {
        return _myIOC.Resolve(type);
    }
    public CultureInfo Culture
    {
        get{ return CultureInfo.GetCultureInfo("es-ES"); }
    }
    public bool RecognizeHelp{get{return true;}}
    
    public Func GetTypeconverter()
    {
        return TypeConverter;
    }
}

This configuration will have a Global variable (that is, a parameter that can be set for any action). It will have a required global parameter (you must set that parameter in order to run any action). Note that you can insert your own type converter (how the strings will be converted to different values in the controller action parameters).

Why enter culture code? Isop tries as much as possible to adhere to the user specified culturecode. This have some implications for people using sv-SE or any other culture where the standard date formatting does not fit.

Since Isop does not know your IOC it provides a hook (ObjectFactory) in order to be able to resolve the controllers.

The same configuration class can be consumed by the fluent api:


static void Main(string[] args)
{
    var configuration = new IsopConfiguration();
    new Build()
      .Configuration(configuration)
      .Parse(args)
      .Invoke(Console.Out);
}

You can invoke your program by (where you have Isop.Cli.exe in the same folder as your dll or exe containing the above class)

Isop.Cli.exe Customer Add --name value

Look at the Example Cli project for the most recent example of how it is used.

Runners

Nuget feed for isop project on appveyor

Alternative

The alternative for this kind of library is the framework found in fubucore.

If you want to have something simpler for simple command line applications then I would recommend using ndesc options.