Class EnvironmentParser

Handles parsing of environment variables by default or optionally variables from a custom source. This has built-in methods for parsing: int, long, double, TimeSpan, string and enum variables as well as mechanisms to parse custom types.

note

This class logs details about parsed variables. By default, these logs include actual value that could not be parsed. This may not be desirable for variables defining secrets. Pass redact: true for these cases.

When debugging, it's useful to ignore redact arguments and include these values in any logged events anyway. You can accomplish this by setting the NEON_REDACT_OVERRIDE=1 environment variable.

IMPORTANT: Never set NEON_REDACT_OVERRIDE=1 for production.

Inheritance

object

EnvironmentParser

Namespace: Neon.Common

Assembly: Neon.Common.dll

Syntax

public class EnvironmentParser

Constructors

EnvironmentParser(ILogger, VariableSource)

Constructor.

Declaration

public EnvironmentParser(ILogger logger = null, EnvironmentParser.VariableSource source = null)

Parameters

Type	Name	Description
ILogger	logger	Optionally specifies the logger where parsing errors will be logged.
EnvironmentParser.VariableSource	source	Optionally specifies an alternative variable source. This defaults to retrieving environment variables.

Methods

Get(string, bool, bool, Validator<bool>)

Attempts to parse an environment variable as a bool, writting messages to the associated logger if one was passed to the constructor.

Declaration

public bool Get(string variable, bool defaultInput, bool required = false, EnvironmentParser.Validator<bool> validator = null)

Parameters

Type	Name	Description
string	variable	The variable name.
bool	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<bool>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.

Returns

Type	Description
bool	The parsed value.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Get(string, double, bool, Validator<double>)

Attempts to parse an environment variable as an double, writting messages to the associated logger if one was passed to the constructor.

Declaration

public double Get(string variable, double defaultInput, bool required = false, EnvironmentParser.Validator<double> validator = null)

Parameters

Type	Name	Description
string	variable	The variable name.
double	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<double>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.

Returns

Type	Description
double	The parsed value.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Get(string, int, bool, Validator<int>)

Attempts to parse an environment variable as an int, writting messages to the associated logger if one was passed to the constructor.

Declaration

public int Get(string variable, int defaultInput, bool required = false, EnvironmentParser.Validator<int> validator = null)

Parameters

Type	Name	Description
string	variable	The variable name.
int	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<int>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.

Returns

Type	Description
int	The parsed value.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Get(string, long, bool, Validator<long>)

Attempts to parse an environment variable as a long, writting messages to the associated logger if one was passed to the constructor.

Declaration

public long Get(string variable, long defaultInput, bool required = false, EnvironmentParser.Validator<long> validator = null)

Parameters

Type	Name	Description
string	variable	The variable name.
long	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<long>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.

Returns

Type	Description
long	The parsed value.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Get(string, string, bool, Validator<string>, bool)

Attempts to parse an environment variable as a string, writting messages to the associated logger if one was passed to the constructor.

Declaration

public string Get(string variable, string defaultInput, bool required = false, EnvironmentParser.Validator<string> validator = null, bool redact = false)

Parameters

Type	Name	Description
string	variable	The variable name.
string	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<string>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.
bool	redact	Optionally redact log output of the variable.

Returns

Type	Description
string	The parsed value.

Remarks

note

This class logs details about parsed variables. By default, these logs include actual value that could not be parsed. This may not be desirable for variables defining secrets. Pass redact: true for these cases.

When debugging, it's useful to ignore redact arguments and include these values in any logged events anyway. You can accomplish this by setting the NEON_REDACT_OVERRIDE=1 environment variable.

IMPORTANT: Never set NEON_REDACT_OVERRIDE=1 for production.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Get(string, TimeSpan, bool, Validator<TimeSpan>)

Attempts to parse an environment variable as a TimeSpan, writting messages to the associated logger if one was passed to the constructor.

Declaration

public TimeSpan Get(string variable, TimeSpan defaultInput, bool required = false, EnvironmentParser.Validator<TimeSpan> validator = null)

Parameters

Type	Name	Description
string	variable	The variable name.
TimeSpan	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<TimeSpan>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.

Returns

Type	Description
TimeSpan	The parsed value.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Get<TEnum>(string, TEnum, bool, Validator<TEnum>)

Attempts to parse an environment variable as an eumeration, writting messages to the associated logger if one was passed to the constructor.

Declaration

public TEnum Get<TEnum>(string variable, TEnum defaultInput, bool required = false, EnvironmentParser.Validator<TEnum> validator = null) where TEnum : struct, Enum

Parameters

Type	Name	Description
string	variable	The variable name.
TEnum	defaultInput	The default value.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<TEnum>	validator	Optional validation function to be called to verify that the parsed variable value is valid. This should return null for valid values and an error message for invalid ones.

Returns

Type	Description
TEnum	The parsed value.

Type Parameters

Name	Description
TEnum	The desired enumeration type.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.

Parse<T>(string, string, Parser<T>, bool, Validator<T>, bool)

Attempts to parse an environment variable as a T, writting messages to the associated logger if one was passed to the constructor.

Declaration

public T Parse<T>(string variable, string defaultInput, EnvironmentParser.Parser<T> parser, bool required = false, EnvironmentParser.Validator<T> validator = null, bool redact = false)

Parameters

Type	Name	Description
string	variable	The variable name.
string	defaultInput	The default value.
EnvironmentParser.Parser<T>	parser	The parser function.
bool	required	Optionally specifies that the variable is required to exist.
EnvironmentParser.Validator<T>	validator	Optional validation function.
bool	redact	Optionally redact log output of the variable.

Returns

Type	Description
T	The parsed value.

Type Parameters

Name	Description
T	The parsed output type.

Remarks

note

This class logs details about parsed variables. By default, these logs include actual value that could not be parsed. This may not be desirable for variables defining secrets. Pass redact: true for these cases.

When debugging, it's useful to ignore redact arguments and include these values in any logged events anyway. You can accomplish this by setting the NEON_REDACT_OVERRIDE=1 environment variable.

IMPORTANT: Never set NEON_REDACT_OVERRIDE=1 for production.

Exceptions

Type	Condition
KeyNotFoundException	Thrown if the variable does not exists and required=true.
FormatException	Thrown if the variable could not be parsed or the validator returned an error.