Integration with IHost #

Oakton works well with the generic HostBuilder in .Net Core and .Net 5 to extend the command line support of your applications.

• An improved, default run command
• A new command for environment check support
• Ability to add your own commands running in the context of your application
• Extensible diagnostic data about your application

To enable the extended command line options in your .Net application bootstrapped by IHostBuilder, first install the Oakton nuget to your project. Then modify the Program.Main() method generated by the typical .Net project templates as shown in some of the examples below:

.Net 6 Console Integration #

In .Net 6, you have the option to allow .Net to magically create a Program.Main() entry point over the code in the Program file. Oakton integration with IHost works every so slightly differently than the .Net 5 and before versions, but you can see an example below:

using Oakton;

var builder = WebApplication.CreateBuilder(args);

// This isn't required, but it "helps" Oakton to enable
// some additional diagnostics for the stateful resource 
// model
builder.Host.ApplyOaktonExtensions();

var app = builder.Build();
app.MapGet("/", () => "Hello World!");

// Note the usage of await to force the implied
// Program.Main() method to be asynchronous
return await app.RunOaktonCommands(args);

^{snippet source | anchor}

Just note that the return await app.RunOaktonCommands(args); line at the bottom is important because:

1. Using return here tells .Net to make the Program.Main() return an exit code that the OS itself needs in order to understand if an execution was successful or not -- and one of the common usages of Oakton is to create validation commands that require this.
2. Using await here tells .Net to make Program.Main() return Task<int> and execute asynchronously instead of Oakton having to do evil .GetAwaiter().GetResult() calls behind the scenes.
3. RunOaktonCommands() makes the .Net program use Oakton as the command line executor to begin with

"Old School Program.Main()" #

Oakton usage for "old school" < .Net 6 applications is very similar:

public class Program
{
    public static Task<int> Main(string[] args)
    {
        return CreateHostBuilder(args)
            
            // This extension method replaces the calls to
            // IWebHost.Build() and Start()
            .RunOaktonCommands(args);
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(x => x.UseStartup<Startup>());
    
}

^{snippet source | anchor}

or with IWebHostBuilder:

public class Program
{
    public static Task<int> Main(string[] args)
    {
        return CreateWebHostBuilder(args)
            
            // This extension method replaces the calls to
            // IWebHost.Build() and Start()
            .RunOaktonCommands(args);
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
    
}

^{snippet source | anchor}

There are just a couple things to note:

1. The return value of the Program.Main() method now needs to be Task<int> rather than void. This is done so that Oakton can return either successful or failure exit codes for usage in diagnostic commands you may want to stop automated builds upon failures.
2. You will use the RunOaktonCommands() method to accept the command line arguments and invoke your system rather than manually building and/or starting the IWebHost yourself

Combining Serilog with Oakton #

If you're having any issues with Serilog logging while using Oakton, please see this StackOverflow issue.