Rocketmakers.Environment.Generation 2.1.2

Rocketmakers.Environment

These set of packages are used to describe the contract your application has to its running environment, and make this contract available to other downstream consumers of your application.

Definition

You can define a (machine readable) JSON/YAML file, that will be used to generate a C# Environment class for consumption in your application

{
  "$schema": "https://docs.rocketmakers.club/environment/schema/v1.json",
  "version": 1,
  "name": "Authentication",
  "prefix": "AUTH",
  "variables": [
    { "kind": "string", "name": "TOKEN", "secret": true },
    { "kind": "string", "name": "NAME", "optional": true },
    { "kind": "string", "name": "CONTACTS", "optional": true, "array": true },
    { "kind": "number", "name": "RATE" },
    { "kind": "integer", "name": "PORT" },
    { "kind": "file-path", "name": "RSA_FILE", "secret": true }
  ]
}

Note: secret is purely advisory for any consumers, and not directly used within this package!

You can then use the CLI tool to generate a .NET implementation matching the contract for your application. This will have a dependency on our supporting library Rocketmakers.Environment.

Packages

Rocketmakers.Environment.Generation

This contains the main logic for generating a consumable C# class which matches the contract of a given environment schema. The main entry point for this is via the Generator class.

var generator = new Generator();
var inputFilePath = 'path/to/environment/definition.json';

var content = await generator.GenerateAsync(inputFilePath, new GeneratorOptions('MyApplicationNamespace'));

...which for the example definition above would produce something like...

//<autogenerated />
// DO NOT EDIT! This class is automatically generated using Rocketmakers.Environment.Generation.

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Rocketmakers.Environment;

namespace MyApplicationNamespace;

public partial record AuthenticationDefaults
{
    public string Token { get; set; }

    public string Name { get; set; }

    public IEnumerable<string> Contacts { get; set; }

    public decimal? rate { get; set; }

    public int? Port { get; set; }

    public string RsaFile { get; set; }
}

public partial class Authentication
{
    public string Token { get; init; }

    public string Name { get; init; }

    public IEnumerable<string> Contacts { get; init; }

    public decimal rate { get; init; }

    public int Port { get; init; }

    public string RsaFile { get; init; }


    public static async Task<Authentication> ConfigureAsync(IEnvironmentProvider provider, AuthenticationDefaults defaults)
    {
        // Generated code is here, but removed for demonstration purposes //
    }

    public static Authentication Configure(IEnvironmentProvider provider, AuthenticationDefaults defaults)
    {
        // Generated code is here, but removed for demonstration purposes //
    }

    public static Task<Authentication> ConfigureAsync(IEnvironmentProvider provider, Action<AuthenticationDefaults> constructDefaults)
    {
        // Generated code is here, but removed for demonstration purposes //
    }

    public static Authentication Configure(IEnvironmentProvider provider, Action<AuthenticationDefaults> constructDefaults)
    {
        // Generated code is here, but removed for demonstration purposes //
    }

    public static Task<Authentication> ConfigureAsync(IEnvironmentProvider provider)
    {
        // Generated code is here, but removed for demonstration purposes //
    }

    public static Authentication Configure(IEnvironmentProvider provider)
    {
        // Generated code is here, but removed for demonstration purposes //
    }
}

...which would then be consumed something like...

var config = Authentication.Load
(
    new EnvironmentVariableProvider(),
    new AuthenticationDefaults()
    {
      Name = "Default Name"
    }
);

Rocketmakers.Environment.Generation.Cli

This package contains a .NET CLI tool for exposing Rocketmakers.Environment.Generation functionality via the command line.

Please note, at the present time the CLI tool only supports JSON files.

Installation

Before you install, it is suggested you create a dotnet tool manifest. This ensures that all developers working on your code base use the same version of the tool. This can be done by running the following command

dotnet new tool-manifest

You can then install the tool with the following command to install the latest version.

dotnet tool install Rocketmakers.Environment.Generation.Cli

Running The Tool

You can then run the tool with the following command

dotnet tool run rocketmakers-environment-cli -i /path/to/environment/definition.json -o /path/to/output/generated/code.cs -n MyNamespace

Rocketmakers.Environment

This is a supporting package required by the code generated by Rocketmakers.Environment.Generation. It provides interfaces and default implementations that the generated code relies upon. This includes a default providers for retrieving the environment data from environment variables or dotenv files, but also the interface for the contract if you want to retrieve them from somewhere else (e.g. cloud secret manager).