himl 0.6.0

himl

Core library for himl.net (Hierarchical YAML configuration for .NET).

Installation

Install the library package:

dotnet add package himl

Or via Package Manager Console:

Install-Package himl

Basic Usage

Merge simple/default.yaml with simple/production/env.yaml:

using himl;
using himl.core;

var processor = new ConfigurationProcessor(/* dependencies via DI */);
var options = new HimlOptions
{
    OutputFormat = OutputFormat.Yaml,
    ListMergeStrategy = ListMergeStrategy.AppendUnique
};

var result = await processor.ProcessAsync("examples/simple/production", options);
Console.WriteLine(result.Output);

Using with Microsoft.Extensions.Configuration

himl.net integrates seamlessly with the .NET configuration system:

using himl.Extensions;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// Add HIML configuration source using the complex example
builder.Configuration.AddHiml("examples/complex/env=dev/region=us-east-1/cluster=cluster1", options =>
{
    options.ListMergeStrategy = ListMergeStrategy.AppendUnique;
    options.DictMergeStrategy = DictMergeStrategy.Merge;
});

var host = builder.Build();

// Access configuration values from the complex example
var config = host.Services.GetRequiredService<IConfiguration>();
var environment = config["env"];              // "dev"
var region = config["region"];               // "us-east-1"
var cluster = config["cluster"];             // "cluster1"
var clusterName = config["cluster_info:name"];           // "default"
var nodeType = config["cluster_info:node_type"];         // "c3.2xlarge"
var cpuMetric = config["cluster_metrics:0:metric"];      // "cpu"
var cpuValue = config["cluster_metrics:0:value"];        // "90"

Secret Resolution

The library supports multiple secret managers for resolving secrets in your configuration:

// Example configuration with secrets
builder.Configuration.AddHiml("config/production", options =>
{
    options.SkipSecrets = false;  // Enable secret resolution (default)
});

// Configuration file can reference secrets:
// database:
//   password: "${gcp-sm://my-project/db-password/latest}"
//   apiKey: "${ssm:/app/api-key}"
//   certificate: "${vault:/secret/data/ssl:cert}"
//   backup: "${s3:backup-bucket:credentials.json}"

Supported secret managers:

• Google Secret Manager: ${gcp-sm://project-id/secret-name/version}
• AWS Systems Manager: ${ssm:/parameter/path}
• AWS S3: ${s3:bucket-name:object-key}
• HashiCorp Vault: ${vault:/secret/path:key}

Authentication is handled through the respective cloud provider SDKs using default credential chains.

You can also chain multiple HIML sources with different merge strategies:

builder.Configuration
    .AddHiml("examples/complex")  // Base configuration
    .AddHiml("examples/complex/env=dev/region=us-east-1/cluster=cluster1", options =>
    {
        options.SkipInterpolations = false;
    })
    .AddHiml("examples/complex/overrides", optional: true);  // Optional overrides

For full documentation and examples, see the repository README: https://github.com/aniongithub/himl.net

Using the CLI

The himl.cli CLI tool provides exact parity with the original Adobe HIML himl-config-merger tool. It generates configuration files from hierarchical YAML.

Install the CLI tool:

dotnet tool install -g himl.cli

Basic usage:

himl.cli <path> --output-dir <output-dir> --levels <levels...> --leaf-directories <leaf-directories...>

Example:

himl.cli examples/complex --output-dir /tmp/output --levels env region cluster --leaf-directories cluster

For full documentation and examples, see the repository README: https://github.com/aniongithub/himl.net