Class Environment

Namespace

Sdl3Sharp.Utilities

Assembly

Sdl3Sharp.dll

Represents a set of environment variables

public sealed class Environment : IDisposable, IEnumerable<KeyValuePair<string, string>>, IEnumerable, IEquatable<Environment>

Inheritance

object

Environment

Implements

IDisposable

IEnumerable<KeyValuePair<string, string>>

IEnumerable

IEquatable<Environment>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Operations on instances of this class are thread-safe, except when using the TryGetProcessVariableUnsafe(string, out string?), TrySetProcessVariableUnsafe(string, string, bool), and TryUnsetProcessVariableUnsafe(string) methods."/>

Constructors

Environment(bool)

Creates a new set of environment variables

public Environment(bool populateFromRuntime = false)

Parameters

populateFromRuntime bool

Indicates whether the newly created Environment should be initialized with the environment variables from the C runtime environment

Remarks

If populateFromRuntime is set to false (its default value), it is safe to call this constructor from any thread, otherwise it is only safe to call, if there are no other threads that are calling TrySetProcessVariableUnsafe(string, string, bool) or TryUnsetProcessVariableUnsafe(string).

In contrast to most of the remaining API which uses the Try-method pattern, this constructor intentionally fails by throwing an exception. If you want to handle failures wrap the call to this constructor in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't create a new Environment

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Equals(Environment?)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Environment? other)

Parameters

other Environment

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to the current object.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current object.

Returns

bool

true if the specified object is equal to the current object; otherwise, false.

~Environment()

protected ~Environment()

GetEnumerator()

Gets an Environment.Enumerator for the current set of environment variables

public Environment.Enumerator GetEnumerator()

Returns

Environment.Enumerator

An Environment.Enumerator for the current set of environment variables

Remarks

In contrast to most of the remaining API which uses the Try-method pattern, this method intentionally fails by throwing an exception. If you want to handle failures wrap the call to this method in a try-block, and check TryGet(out string?) for more information when catching a SdlException.

Exceptions

SdlException

Couldn't create an Environment.Enumerator instance for the current set of environment variables

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object.

TryGetProcessEnumerator(out Enumerator?)

Tries to enumerator the process environment variables

public static bool TryGetProcessEnumerator(out Environment.Enumerator? enumerator)

Parameters

enumerator Environment.Enumerator

The resulting Environment.Enumerator to enumerate the process environment variables, when this method returns true; otherwise, null

Returns

bool

true if an Environment.Enumerator for the process environment variables were successfully created; otherwise, false (check TryGet(out string?) for more information)

Remarks

Use the resulting enumerator to enumerate the process environment variables.

TryGetProcessVariable(string, out string?)

Tries to get the value of a process environment variable

public static bool TryGetProcessVariable(string name, out string? value)

Parameters

name string

The name of the variable to get

value string

The value of the environment variable, when this method returns true; otherwise, default(string?)

Returns

bool

true if the process environment variable exists and its value could get retrieved successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method uses SDL's cached copy of the process environment and therefore is thread-safe.

Alternatively to this method, you could use TryGetVariable(string, out string?) on ProcessEnvironment instead.

TryGetProcessVariableUnsafe(string, out string?)

Tries to get the value of a process environment variable

public static bool TryGetProcessVariableUnsafe(string name, out string? value)

Parameters

name string

The name of the variable to get

value string

The value of the environment variable, when this method returns true; otherwise, default(string?)

Returns

bool

true if the process environment variable exists and its value could get retrieved successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method bypasses SDL's cached copy of the process environment and therefore is not thread-safe.

TryGetVariable(string, out string?)

Tries to get the value of an environment variable in the current Environment

public bool TryGetVariable(string name, out string? value)

Parameters

name string

The name of the variable to get

value string

The value of the environment variable, when this method returns true; otherwise, default(string?)

Returns

bool

true if the environment variable exists in the current Environment and its value could get retrieved successfully; otherwise, false (check TryGet(out string?) for more information)

TrySetProcessVariableUnsafe(string, string, bool)

Tries to set a process environment variable

public static bool TrySetProcessVariableUnsafe(string name, string value, bool overwrite = true)

Parameters

name string

The name of the variable to set

value string

The value of the environment variable to set to

overwrite bool

Indicates whether the value an existing environment variable should be overwritten. If set to true, the value of the environment variable will be set to the given value, even if the variable already exists; otherwise, if set to false, an existing environment variable will not be changed while this method will still return successfully.

Returns

bool

true if the process environment variable was successfully set to value, or if overwrite was set to false and the environment variable already existed; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is not thread-safe, consider using TrySetVariable(string, string, bool) on ProcessEnvironment instead.

TrySetVariable(string, string, bool)

Tries to set an environment variable in the current Environment

public bool TrySetVariable(string name, string value, bool overwrite = true)

Parameters

name string

The name of the variable to set

value string

The value of the environment variable to set to

overwrite bool

Indicates whether the value an existing environment variable should be overwritten. If set to true, the value of the environment variable will be set to the given value, even if the variable already exists; otherwise, if set to false, an existing environment variable will not be changed while this method will still return successfully.

Returns

bool

true if the environment variable in the current Environment was successfully set to value, or if overwrite was set to false and the environment variable already existed; otherwise, false (check TryGet(out string?) for more information)

TryUnsetProcessVariableUnsafe(string)

Tries to clear a process environment variable (remove it from the environment)

public static bool TryUnsetProcessVariableUnsafe(string name)

Parameters

name string

The name of the variable to clear

Returns

bool

true if the process environment variable was successfully cleared; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method is not thread-safe, consider using TryUnsetVariable(string) on ProcessEnvironment instead.

TryUnsetVariable(string)

Tries to clear an environment variable in the current Environment (remove it from the environment)

public bool TryUnsetVariable(string name)

Parameters

name string

The name of the variable to clear

Returns

bool

true if the environment variable in the current Environment was successfully cleared; otherwise, false (check TryGet(out string?) for more information)