Walkthrough

In this tutorial we will set up BindSight in an empty dotnet console application.

To do this, we will follow the following steps:

create an empty console application
set up a service collection
create an option type
bind the option type using the options pattern
add BindSight to the application
run the BindSight generators

Setting up the Application

Create an empty console application:
```
dotnet new console -n BindSightTutorial
```

Install the required packages:

dotnet add package RhoMicro.BindSight
dotnet add package Microsoft.Extensions.DependencyInjection
dotnet add package Microsoft.Extensions.Configuration.CommandLine
dotnet add package Microsoft.Extensions.Options.ConfigurationExtensions

Add the required using statements to the Program.cs file:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using RhoMicro.BindSight;
using RhoMicro.BindSight.Services;

Create a new service collection, add a command line configuration provider and register the configuration to the service collection:

var configurationBuilder = new ConfigurationBuilder().AddCommandLine(args);

var services = new ServiceCollection()
    .AddLogging(loggingBuilder => loggingBuilder.AddConsole())
    .AddSingleton(_ => configurationBuilder.Build())
    .AddSingleton<IConfiguration>(serviceProvider => serviceProvider.GetRequiredService<IConfigurationRoot>());

Adding an Option Type

Create a new TutorialOptions.cs file and add a custom option type:

class TutorialOptions
{
    public string Value { get; set; } = string.Empty;
}

Bind the option type against the configuration using the options pattern:
```
services.AddOptions<TutorialOptions>().BindConfiguration("Tutorial");
```

Create a service provider, resolve an instance of the option type and print its property to the console:

var serviceProvider = services.BuildServiceProvider();

var argument = serviceProvider
    .GetRequiredService<IOptions<TutorialOptions>>()
    .Value
    .Argument;

Console.WriteLine(argument);

Running the Application

In order to verify the option binding, we run the application using the following commandline argument:
```
dotnet run --Tutorial:Argument="Hello, World!"
```
We can observe the application echoing the argument back at us.
```
> dotnet run --Tutorial:Argument="Hello, World!"
Hello, World
```

Integrating BindSight

Replace the options binding

services.AddOptions<TutorialOptions>().BindConfiguration("Tutorial");

with the following:

services.AddDocumentedOptions<TutorialOptions>("Tutorial");

Generating Documentation

Note that the binding is equivalent to the previous solution. We can verify this by running the application again:

> dotnet run --Tutorial:Argument="Hello, World!"
Hello, World!

Resolve the generator runner and run it, printing the run result:

var runner = serviceProvider.GetRequiredService<BindSightGeneratorRunner>();

var generatorsRan = await runner.Run(CancellationToken.None);

Console.WriteLine($"Generators ran: {generatorsRan}");

The output indicates that the generators did not run:

> dotnet run --Tutorial:Argument="Hello, World!"
Hello, World!
Generators ran: False

To enable generators, we may provide another command line argument:

dotnet run --Tutorial:Argument="Hello, World" --BindSightRunnerOptions:Run=true

The output now includes logs of the generators being ran:

> dotnet run --Tutorial:Argument="Hello, World" --BindSightRunnerOptions:Run=true
Hello, World
info: RhoMicro.BindSight.Services.BindSightGeneratorRunner[0]
      Running generators.

...

info: RhoMicro.BindSight.Services.BindSightGeneratorRunner[0]
      Done running generators.
info: RhoMicro.BindSight.Services.BindSightGeneratorRunner[0]
      Exiting with mode 'Environment'.

An Options directory was created in the project directory by the generators. It contains a Readme.md file detailing detected options mappings. A section for our TutorialOptions was created as well:

Tutorial


Key	`Tutorial`
Type	`TutorialOptions` `TutorialOptions`
Disallowed Values	`null`

Properties

Argument


Key	`Tutorial:Argument`
Type	`string`
Disallowed Values	`null`

Conclusion

In this tutorial we set up a new dotnet console application and used the options pattern to configure a custom option type. We then integrated BindSight into our application and generated a readme file detailing the configurable options used by the application.