|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System;
using System.Collections.Generic;
using Microsoft.Extensions.Configuration.CommandLine;
namespace Microsoft.Extensions.Configuration
{
/// <summary>
/// Extension methods for registering <see cref="CommandLineConfigurationProvider"/> with <see cref="IConfigurationBuilder"/>.
/// </summary>
public static class CommandLineConfigurationExtensions
{
/// <summary>
/// Adds a <see cref="CommandLineConfigurationProvider"/> <see cref="IConfigurationProvider"/>
/// that reads configuration values from the command line.
/// </summary>
/// <param name="configurationBuilder">The <see cref="IConfigurationBuilder"/> to add to.</param>
/// <param name="args">The command line args.</param>
/// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
/// <remarks>
/// <para>
/// The values passed on the command line, in the <c>args</c> string array, should be a set
/// of keys prefixed with two dashes ("--") and then values, separate by either the
/// equals sign ("=") or a space (" ").
/// </para>
/// <para>
/// A forward slash ("/") can be used as an alternative prefix, with either equals or space, and when using
/// an equals sign the prefix can be left out altogether.
/// </para>
/// <para>
/// There are five basic alternative formats for arguments:
/// <c>key1=value1 --key2=value2 /key3=value3 --key4 value4 /key5 value5</c>.
/// </para>
/// </remarks>
/// <example>
/// A simple console application that has five values.
/// <code>
/// // dotnet run key1=value1 --key2=value2 /key3=value3 --key4 value4 /key5 value5
///
/// using Microsoft.Extensions.Configuration;
/// using System;
///
/// namespace CommandLineSample
/// {
/// public class Program
/// {
/// public static void Main(string[] args)
/// {
/// var builder = new ConfigurationBuilder();
/// builder.AddCommandLine(args);
///
/// var config = builder.Build();
///
/// Console.WriteLine($"Key1: '{config["Key1"]}'");
/// Console.WriteLine($"Key2: '{config["Key2"]}'");
/// Console.WriteLine($"Key3: '{config["Key3"]}'");
/// Console.WriteLine($"Key4: '{config["Key4"]}'");
/// Console.WriteLine($"Key5: '{config["Key5"]}'");
/// }
/// }
/// }
/// </code>
/// </example>
public static IConfigurationBuilder AddCommandLine(this IConfigurationBuilder configurationBuilder, string[] args)
{
return configurationBuilder.AddCommandLine(args, switchMappings: null);
}
/// <summary>
/// Adds a <see cref="CommandLineConfigurationProvider"/> <see cref="IConfigurationProvider"/> that reads
/// configuration values from the command line using the specified switch mappings.
/// </summary>
/// <param name="configurationBuilder">The <see cref="IConfigurationBuilder"/> to add to.</param>
/// <param name="args">The command line args.</param>
/// <param name="switchMappings">
/// The switch mappings. A dictionary of short (with prefix "-") and
/// alias keys (with prefix "--"), mapped to the configuration key (no prefix).
/// </param>
/// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
/// <remarks>
/// <para>
/// The <c>switchMappings</c> allows additional formats for alternative short and alias keys
/// to be used from the command line. Also see the basic version of <c>AddCommandLine</c> for
/// the standard formats supported.
/// </para>
/// <para>
/// Short keys start with a single dash ("-") and are mapped to the main key name (without
/// prefix), and can be used with either equals or space. The single dash mappings are intended
/// to be used for shorter alternative switches.
/// </para>
/// <para>
/// Note that a single dash switch cannot be accessed directly, but must have a switch mapping
/// defined and accessed using the full key. Passing an undefined single dash argument will
/// cause as <c>FormatException</c>.
/// </para>
/// <para>
/// There are two formats for short arguments:
/// <c>-k1=value1 -k2 value2</c>.
/// </para>
/// <para>
/// Alias key definitions start with two dashes ("--") and are mapped to the main key name (without
/// prefix), and can be used in place of the normal key. They also work when a forward slash prefix
/// is used in the command line (but not with the no prefix equals format).
/// </para>
/// <para>
/// There are only four formats for aliased arguments:
/// <c>--alt3=value3 /alt4=value4 --alt5 value5 /alt6 value6</c>.
/// </para>
/// </remarks>
/// <example>
/// A simple console application that has two short and four alias switch mappings defined.
/// <code>
/// // dotnet run -k1=value1 -k2 value2 --alt3=value2 /alt4=value3 --alt5 value5 /alt6 value6
///
/// using Microsoft.Extensions.Configuration;
/// using System;
/// using System.Collections.Generic;
///
/// namespace CommandLineSample
/// {
/// public class Program
/// {
/// public static void Main(string[] args)
/// {
/// var switchMappings = new Dictionary<string, string>()
/// {
/// { "-k1", "key1" },
/// { "-k2", "key2" },
/// { "--alt3", "key3" },
/// { "--alt4", "key4" },
/// { "--alt5", "key5" },
/// { "--alt6", "key6" },
/// };
/// var builder = new ConfigurationBuilder();
/// builder.AddCommandLine(args, switchMappings);
///
/// var config = builder.Build();
///
/// Console.WriteLine($"Key1: '{config["Key1"]}'");
/// Console.WriteLine($"Key2: '{config["Key2"]}'");
/// Console.WriteLine($"Key3: '{config["Key3"]}'");
/// Console.WriteLine($"Key4: '{config["Key4"]}'");
/// Console.WriteLine($"Key5: '{config["Key5"]}'");
/// Console.WriteLine($"Key6: '{config["Key6"]}'");
/// }
/// }
/// }
/// </code>
/// </example>
public static IConfigurationBuilder AddCommandLine(
this IConfigurationBuilder configurationBuilder,
string[] args,
IDictionary<string, string>? switchMappings)
{
configurationBuilder.Add(new CommandLineConfigurationSource { Args = args, SwitchMappings = switchMappings });
return configurationBuilder;
}
/// <summary>
/// Adds an <see cref="IConfigurationProvider"/> that reads configuration values from the command line.
/// </summary>
/// <param name="builder">The <see cref="IConfigurationBuilder"/> to add to.</param>
/// <param name="configureSource">Configures the source.</param>
/// <returns>The <see cref="IConfigurationBuilder"/>.</returns>
public static IConfigurationBuilder AddCommandLine(this IConfigurationBuilder builder, Action<CommandLineConfigurationSource>? configureSource)
=> builder.Add(configureSource);
}
}
|