|
| 1 | +### Usage: Automatic Binding |
| 2 | + |
| 3 | +Automatic binding has the framework discover the properties you want to |
| 4 | +bind to options. You indicate the bound properties by decorating them |
| 5 | +with an `OptionKeys` attribute. Either static or instance properties can |
| 6 | +be used, provided they are publicly read/write and there is an ITextConverter |
| 7 | +type defined in the framework which supports their type. |
| 8 | + |
| 9 | +There are other attributes you can use to provide additional information |
| 10 | +to the framework, to configure the bound options the way you want. |
| 11 | + |
| 12 | +Here's an example, from the AutoBindExample project: |
| 13 | + |
| 14 | +``` |
| 15 | +using System; |
| 16 | +using System.Collections.Generic; |
| 17 | +using System.ComponentModel; |
| 18 | +using Autofac; |
| 19 | +using Autofac.Extensions.DependencyInjection; |
| 20 | +using J4JSoftware.CommandLine; |
| 21 | +using Microsoft.Extensions.DependencyInjection; |
| 22 | +
|
| 23 | +namespace AutoBindExample |
| 24 | +{ |
| 25 | + class Program |
| 26 | + { |
| 27 | + static void Main(string[] args) |
| 28 | + { |
| 29 | + InitializeServiceProvider(); |
| 30 | +
|
| 31 | + var builder = ServiceProvider.GetRequiredService<BindingTargetBuilder>(); |
| 32 | +
|
| 33 | + builder.Prefixes("-", "--", "/") |
| 34 | + .Quotes('\'', '"') |
| 35 | + .HelpKeys("h", "?") |
| 36 | + .Description("a test program for exercising J4JCommandLine") |
| 37 | + .ProgramName($"{nameof(Program)}.exe"); |
| 38 | +
|
| 39 | + var binder = builder.AutoBind<Program>(); |
| 40 | + if (binder == null) |
| 41 | + throw new NullReferenceException(nameof(Program)); |
| 42 | +
|
| 43 | + var intOption = binder.Options[ "i" ]; |
| 44 | + if( intOption != null ) |
| 45 | + intOption.SetValidator( OptionInRange<int>.GreaterThan( 0 ) ); |
| 46 | +
|
| 47 | + if (!binder.Parse(args)) |
| 48 | + { |
| 49 | + Environment.ExitCode = 1; |
| 50 | + return; |
| 51 | + } |
| 52 | +
|
| 53 | + Console.WriteLine($"IntValue is {IntValue}"); |
| 54 | + Console.WriteLine($"TextValue is {TextValue}"); |
| 55 | +
|
| 56 | + Console.WriteLine(Unkeyed.Count == 0 |
| 57 | + ? "No unkeyed parameters" |
| 58 | + : $"Unkeyed parameters: {string.Join(", ", Unkeyed)}"); |
| 59 | + } |
| 60 | +
|
| 61 | + public static IServiceProvider ServiceProvider { get; set; } |
| 62 | +
|
| 63 | + [OptionKeys("i")] |
| 64 | + [DefaultValue(5)] |
| 65 | + [Description("some integer value")] |
| 66 | + public static int IntValue { get; set; } |
| 67 | +
|
| 68 | + [OptionKeys("t")] |
| 69 | + [DefaultValue("abc")] |
| 70 | + [Description("some text value")] |
| 71 | + public static string TextValue { get; set; } |
| 72 | +
|
| 73 | + [OptionKeys()] |
| 74 | + public static List<string> Unkeyed { get; set; } |
| 75 | +
|
| 76 | + private static void InitializeServiceProvider() |
| 77 | + { |
| 78 | + var builder = new ContainerBuilder(); |
| 79 | +
|
| 80 | + builder.RegisterType<FancyConsole>() |
| 81 | + .AsImplementedInterfaces(); |
| 82 | +
|
| 83 | + builder.AddJ4JCommandLine(); |
| 84 | +
|
| 85 | + ServiceProvider = new AutofacServiceProvider(builder.Build()); |
| 86 | + } |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +All you do is create an instance of `BindingTargetBuilder` and then |
| 92 | +call `AutoBind<>` on it. |
| 93 | + |
| 94 | +The attributes you can use to configure the bindings are: |
| 95 | + |
| 96 | +| Attribute | Capability | Comments | |
| 97 | +| --------- | ---------- | -------- | |
| 98 | +| OptionKeys | defines the key(s) for the binding | **required** | |
| 99 | +| OptionRequired | makes the binding required or optional | optional | |
| 100 | +| DefaultValue | specifies a default value | optional | |
| 101 | +| Description | supplies a description | optional | |
| 102 | + |
| 103 | +**Note**: *Because option validators are derived from a generic abstract |
| 104 | +base class you cannot specify validators through attributes*. |
| 105 | + |
| 106 | +Instead, you must retrieve the option you want to validate from the |
| 107 | +binder's Options collection and then specify a validator for it. In the |
| 108 | +example this is done in the following lines: |
| 109 | +``` |
| 110 | +var intOption = binder.Options[ "i" ]; |
| 111 | +if( intOption != null ) |
| 112 | + intOption.SetValidator( OptionInRange<int>.GreaterThan( 0 ) ); |
| 113 | +``` |
| 114 | + |
| 115 | +There's a default/basic help/error display engine in the core library. |
| 116 | +But there's also one that produces fancier output defined in the |
| 117 | +FancyHelpError project. Here's what the output looks like: |
| 118 | + |
| 119 | + |
0 commit comments