Table of Contents

ConfigurationKey Struct

Definition

Namespace
Bodu.Text.Configuration
Assembly
Bodu.Text.Configuration.dll
Package
Bodu.Text.Configuration 1.3.0
Source
ConfigurationKey.Parse.cs

Represents a configuration key in both its raw, file-level form and the logical form used by the resolved view, which is colon-delimited, as Microsoft.Extensions.Configuration expects, under every mapping but Identity.

public readonly struct ConfigurationKey : IEquatable<ConfigurationKey>
Implements
Inherited Members
Extension Methods

Examples

// Default mapping - split on '.' and ':', case-insensitive comparison.
var k1 = new ConfigurationKey("Logging.Level.Default");
var k2 = new ConfigurationKey("logging:level:default");
Console.WriteLine(k1 == k2);              // True - same segment sequence under the default comparer
Console.WriteLine(k1.Path);               // "Logging:Level:Default"
Console.WriteLine(string.Join(",", k1.Segments)); // "Logging,Level,Default"

// Case-sensitive parsing for hosts that distinguish 'Foo' from 'foo'.
var opts = new ConfigurationKeyOptions { CaseSensitive = true };
var k3   = new ConfigurationKey("Foo:Bar", opts);
var k4   = new ConfigurationKey("foo:bar", opts);
Console.WriteLine(k3 == k4);              // False

Remarks

The struct stores the input RawKey verbatim. Path is derived from Segments by the mapping policy from ConfigurationKeyOptions: it is the segments joined with a colon, or, under Identity, which does not split a key, the key as written, its ends trimmed. When LowercaseKeys is set, the segments, and so the path, are lowercased with the invariant culture while the raw key keeps the case it was written in.

Equality compares the segment sequence under the configured comparer; the raw form is informational only.

Under every mapping but Identity, both dotted (logging.level.default) and colon-delimited (logging:level:default) source forms produce the same canonical Path, so consumers can mix the two notations in a document without disturbing the resolved view; under Identity they are two keys. Whitespace around each segment is trimmed, so a . b and a.b are the same key, and a segment of whitespace alone counts as empty; under Identity, which does not split a key, only the ends of the key are trimmed. Control characters are rejected at construction time.

Constructors

ConfigurationKey(string, ConfigurationKeyOptions?)

Initializes a new instance of the ConfigurationKey struct from a raw key string using the supplied options.

public ConfigurationKey(string rawKey, ConfigurationKeyOptions? options = null)

Parameters

rawKey string

The raw key as authored in the configuration source.

options ConfigurationKeyOptions

The key options to apply, or null for the defaults.

Exceptions

ArgumentException

rawKey is null, empty, or contains only whitespace; or, under a mapping other than Identity, a segment was empty or whitespace alone when empty segments are not permitted.

Properties

CaseSensitive

Gets a value indicating whether equality and hashing for this key are case-sensitive.

public bool CaseSensitive { get; }

Property Value

bool

true when ordinal case-sensitive comparison is used; otherwise, false for ordinal-ignore-case.

Path

Gets the logical key path derived from Segments: the segments joined with a colon, or, under Identity, the key as written, its ends trimmed.

public string Path { get; }

Property Value

string

The configuration key path, or the empty string for a default instance.

RawKey

Gets the raw key string exactly as it appeared in the source document.

public string RawKey { get; }

Property Value

string

The original key text, or the empty string for a default instance.

Segments

Gets the segments produced by splitting RawKey on the configured separators, each trimmed of the whitespace around it; under Identity, which does not split a key, the whole key, its ends trimmed, is the one segment.

public ImmutableArray<string> Segments { get; }

Property Value

ImmutableArray<string>

An immutable array of segment strings.

Methods

Equals(ConfigurationKey)

Determines whether this key has the same segment sequence as other under the configured comparer.

public bool Equals(ConfigurationKey other)

Parameters

other ConfigurationKey

The other key to compare with.

Returns

bool

true when the segment sequences are equal under the chosen comparer; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

Parse(string)

Parses a raw configuration key into a ConfigurationKey using the default key options.

public static ConfigurationKey Parse(string rawKey)

Parameters

rawKey string

The raw key to parse.

Returns

ConfigurationKey

A ConfigurationKey built from rawKey.

Exceptions

ArgumentException

rawKey is null, empty, or contains only whitespace, or contains an empty segment, or one of whitespace alone, when empty segments are not permitted.

Parse(string, ConfigurationKeyOptions?)

Parses a raw configuration key into a ConfigurationKey using the supplied options.

public static ConfigurationKey Parse(string rawKey, ConfigurationKeyOptions? options)

Parameters

rawKey string

The raw key to parse.

options ConfigurationKeyOptions

The key options to apply, or null for the defaults.

Returns

ConfigurationKey

A ConfigurationKey built from rawKey.

Exceptions

ArgumentException

rawKey is null, empty, or contains only whitespace, or, under a mapping other than Identity, contains an empty segment, or one of whitespace alone, when empty segments are not permitted.

ToString()

Returns the fully qualified type name of this instance.

public override string ToString()

Returns

string

The fully qualified type name.

TryParse(string?, out ConfigurationKey)

Attempts to parse a raw configuration key.

public static bool TryParse(string? rawKey, out ConfigurationKey result)

Parameters

rawKey string

The raw key to parse.

result ConfigurationKey

When this method returns, contains the parsed key if successful; otherwise, the default key.

Returns

bool

true when parsing succeeded; otherwise, false.

TryParse(string?, ConfigurationKeyOptions?, out ConfigurationKey)

Attempts to parse a raw configuration key using the supplied options.

public static bool TryParse(string? rawKey, ConfigurationKeyOptions? options, out ConfigurationKey result)

Parameters

rawKey string

The raw key to parse.

options ConfigurationKeyOptions

The key options to apply, or null for the defaults.

result ConfigurationKey

When this method returns, contains the parsed key if successful; otherwise, the default key.

Returns

bool

true when parsing succeeded; otherwise, false.

Operators

operator ==(ConfigurationKey, ConfigurationKey)

Determines whether two keys are equal.

public static bool operator ==(ConfigurationKey left, ConfigurationKey right)

Parameters

left ConfigurationKey

The first key to compare.

right ConfigurationKey

The second key to compare.

Returns

bool

true when the keys are equal; otherwise, false.

operator !=(ConfigurationKey, ConfigurationKey)

Determines whether two keys are not equal.

public static bool operator !=(ConfigurationKey left, ConfigurationKey right)

Parameters

left ConfigurationKey

The first key to compare.

right ConfigurationKey

The second key to compare.

Returns

bool

true when the keys differ; otherwise, false.

Applies to

ProductVersions
.NET8, 10