ConfigurationKey Struct
Definition
- Namespace
- Bodu.Text.Configuration
- Assembly
- Bodu.Text.Configuration.dll
- Package
- Bodu.Text.Configuration 1.3.0
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
rawKeystringThe raw key as authored in the configuration source.
optionsConfigurationKeyOptionsThe key options to apply, or null for the defaults.
Exceptions
- ArgumentException
rawKeyis 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
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
otherConfigurationKeyThe other key to compare with.
Returns
Equals(object?)
Indicates whether this instance and a specified object are equal.
public override bool Equals(object? obj)
Parameters
objobjectThe object to compare with the current instance.
Returns
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
rawKeystringThe raw key to parse.
Returns
- ConfigurationKey
A ConfigurationKey built from
rawKey.
Exceptions
- ArgumentException
rawKeyis 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
rawKeystringThe raw key to parse.
optionsConfigurationKeyOptionsThe key options to apply, or null for the defaults.
Returns
- ConfigurationKey
A ConfigurationKey built from
rawKey.
Exceptions
- ArgumentException
rawKeyis 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
rawKeystringThe raw key to parse.
resultConfigurationKeyWhen this method returns, contains the parsed key if successful; otherwise, the default key.
Returns
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
rawKeystringThe raw key to parse.
optionsConfigurationKeyOptionsThe key options to apply, or null for the defaults.
resultConfigurationKeyWhen this method returns, contains the parsed key if successful; otherwise, the default key.
Returns
Operators
operator ==(ConfigurationKey, ConfigurationKey)
Determines whether two keys are equal.
public static bool operator ==(ConfigurationKey left, ConfigurationKey right)
Parameters
leftConfigurationKeyThe first key to compare.
rightConfigurationKeyThe second key to compare.
Returns
operator !=(ConfigurationKey, ConfigurationKey)
Determines whether two keys are not equal.
public static bool operator !=(ConfigurationKey left, ConfigurationKey right)
Parameters
leftConfigurationKeyThe first key to compare.
rightConfigurationKeyThe second key to compare.
Returns
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |