CommandLineConfigurationExtensions.AddCommandLine Method

Definition

Namespace:

Microsoft.Extensions.Configuration

Assembly:

Microsoft.Extensions.Configuration.CommandLine.dll

Package:

Microsoft.Extensions.Configuration.CommandLine v8.0.0

Overloads

AddCommandLine(IConfigurationBuilder, Action<CommandLineConfigurationSource>)	Adds an IConfigurationProvider that reads configuration values from the command line.
AddCommandLine(IConfigurationBuilder, String[])	Adds a CommandLineConfigurationProvider that reads configuration values from the command line.
AddCommandLine(IConfigurationBuilder, String[], IDictionary<String,String>)	Adds a CommandLineConfigurationProvider that reads configuration values from the command line using the specified switch mappings.

AddCommandLine(IConfigurationBuilder, Action<CommandLineConfigurationSource>)

Source:

CommandLineConfigurationExtensions.cs

Adds an IConfigurationProvider that reads configuration values from the command line.

public:
[System::Runtime::CompilerServices::Extension]
 static Microsoft::Extensions::Configuration::IConfigurationBuilder ^ AddCommandLine(Microsoft::Extensions::Configuration::IConfigurationBuilder ^ builder, Action<Microsoft::Extensions::Configuration::CommandLine::CommandLineConfigurationSource ^> ^ configureSource);

public static Microsoft.Extensions.Configuration.IConfigurationBuilder AddCommandLine (this Microsoft.Extensions.Configuration.IConfigurationBuilder builder, Action<Microsoft.Extensions.Configuration.CommandLine.CommandLineConfigurationSource>? configureSource);

static member AddCommandLine : Microsoft.Extensions.Configuration.IConfigurationBuilder * Action<Microsoft.Extensions.Configuration.CommandLine.CommandLineConfigurationSource> -> Microsoft.Extensions.Configuration.IConfigurationBuilder

<Extension()>
Public Function AddCommandLine (builder As IConfigurationBuilder, configureSource As Action(Of CommandLineConfigurationSource)) As IConfigurationBuilder

Parameters

builder

IConfigurationBuilder

The IConfigurationBuilder to add to.

configureSource

Action<CommandLineConfigurationSource>

Configures the source.

Returns

IConfigurationBuilder

The IConfigurationBuilder.

AddCommandLine(IConfigurationBuilder, String[])

Source:

CommandLineConfigurationExtensions.cs

Adds a CommandLineConfigurationProvider that reads configuration values from the command line.

public:
[System::Runtime::CompilerServices::Extension]
 static Microsoft::Extensions::Configuration::IConfigurationBuilder ^ AddCommandLine(Microsoft::Extensions::Configuration::IConfigurationBuilder ^ configurationBuilder, cli::array <System::String ^> ^ args);

public static Microsoft.Extensions.Configuration.IConfigurationBuilder AddCommandLine (this Microsoft.Extensions.Configuration.IConfigurationBuilder configurationBuilder, string[] args);

static member AddCommandLine : Microsoft.Extensions.Configuration.IConfigurationBuilder * string[] -> Microsoft.Extensions.Configuration.IConfigurationBuilder

<Extension()>
Public Function AddCommandLine (configurationBuilder As IConfigurationBuilder, args As String()) As IConfigurationBuilder

Parameters

configurationBuilder

IConfigurationBuilder

The IConfigurationBuilder to add to.

args

String[]

The command line args.

Returns

IConfigurationBuilder

The IConfigurationBuilder.

Examples

A simple console application that has five values.

// 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"]}'");
       }
   }
}

Remarks

The values passed on the command line, in the args string array, should be a set of keys prefixed with two dashes ("--") and then values, separated by either the equals sign ("=") or a space (" "). A forward slash ("/") can be used as an alternative prefix, with either equals or space. When using an equals sign, the prefix can be left out altogether.

There are five basic alternative formats for arguments:

key1=value1
--key2=value2
/key3=value3
--key4 value4
/key5 value5

AddCommandLine(IConfigurationBuilder, String[], IDictionary<String,String>)

Source:

CommandLineConfigurationExtensions.cs

Adds a CommandLineConfigurationProvider that reads configuration values from the command line using the specified switch mappings.

public:
[System::Runtime::CompilerServices::Extension]
 static Microsoft::Extensions::Configuration::IConfigurationBuilder ^ AddCommandLine(Microsoft::Extensions::Configuration::IConfigurationBuilder ^ configurationBuilder, cli::array <System::String ^> ^ args, System::Collections::Generic::IDictionary<System::String ^, System::String ^> ^ switchMappings);

public static Microsoft.Extensions.Configuration.IConfigurationBuilder AddCommandLine (this Microsoft.Extensions.Configuration.IConfigurationBuilder configurationBuilder, string[] args, System.Collections.Generic.IDictionary<string,string>? switchMappings);

static member AddCommandLine : Microsoft.Extensions.Configuration.IConfigurationBuilder * string[] * System.Collections.Generic.IDictionary<string, string> -> Microsoft.Extensions.Configuration.IConfigurationBuilder

<Extension()>
Public Function AddCommandLine (configurationBuilder As IConfigurationBuilder, args As String(), switchMappings As IDictionary(Of String, String)) As IConfigurationBuilder

Parameters

configurationBuilder

IConfigurationBuilder

The IConfigurationBuilder to add to.

args

String[]

The command line args.

switchMappings

IDictionary<String,String>

The switch mappings. A dictionary of short (with prefix "-") and alias keys (with prefix "--"), mapped to the configuration key (no prefix).

Returns

IConfigurationBuilder

The IConfigurationBuilder.

Examples

A simple console application that has two short and four alias switch mappings defined.

// 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"]}'");
       }
   }
}

Remarks

The switchMappings allows additional formats for alternative short and alias keys to be used from the command line. For the standard formats that are supported, see the basic version of AddCommandLine.

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. 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 a FormatException.

There are two formats for short arguments: -k1=value1 and -k2 value2.

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).

There are only four formats for aliased arguments:

--alt3=value3
/alt4=value4
--alt5 value5
/alt6 value6