Environment.SetEnvironmentVariable Method (String, String)

 

Creates, modifies, or deletes an environment variable stored in the current process.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

static member SetEnvironmentVariable : 
        variable:string *
        value:string -> unit

Parameters

variable
Type: System.String

The name of an environment variable.

value
Type: System.String

A value to assign to variable.

Exception Condition
ArgumentNullException

variable is null.

ArgumentException

variable contains a zero-length string, an initial hexadecimal zero character (0x00), or an equal sign ("=").

-or-

The length of variable or value is greater than or equal to 32,767 characters.

-or-

An error occurred during the execution of this operation.

SecurityException

The caller does not have the required permission to perform this operation.

Calling this method is equivalent to calling the SetEnvironmentVariable(String, String, EnvironmentVariableTarget) overload with a value of EnvironmentVariableTarget.Process for the target argument.

If the value argument is not empty (see the discussion of deleting an environment variable later in this section for the definition of an empty value) and the environment variable named by the variable parameter does not exist, the environment variable is created and assigned the contents of value. If it does exist, its value is modified. Because the environment variable is defined in the environment block of the current process only, it does not persist after the process has ended.

If variable contains a non-initial hexadecimal zero character, the characters before the zero character are considered the environment variable name and all subsequent characters are ignored.

If value contains a non-initial hexadecimal zero character, the characters before the zero character are assigned to the environment variable and all subsequent characters are ignored.

If value is empty and the environment variable named by variable exists, the environment variable is deleted. If variable does not exist, no error occurs even though the operation cannot be performed. value is considered empty under any of the following conditions:

  • It is null.

  • It is String.Empty.

  • It consists of a single character whose value is U+0000.

The following example tests whether an environment variable named APPDOMAIN exists in the current process. If it does not, it creates it and sets its value to "True". If the value of the APPDOMAIN environment variable is "True", it calls the Message.Display method in a new application domain. Otherwise, it executes the Message.Display method in the current application domain.

No code example is currently available or this language may not be supported.

If you run the example for the first time, the message "Executing in domain Domain2" displays to the console. If you set the environment variable from the command line by using the command:

Set AppDomain=False

the example displays the message "Executing in domain exeName.exe", where exeName is the name of the executable.

The following example attempts to retrieve the value of an environment variable named Test1 from the process environment block. If the variable doesn't exist, the example creates the variable and retrieves its value. The example displays the value of the variable. If the example created the variable, it also calls the GetEnvironmentVariables(EnvironmentVariableTarget) method with each member of the EnvironmentVariableTarget enumeration to establish that the variable can be retrieved only from the current process environment block. Finally, if the example created the variable, it deletes it.

No code example is currently available or this language may not be supported.

EnvironmentPermission

for full access to environment variables. Associated enumeration: Unrestricted

Universal Windows Platform
Available since 10
.NET Framework
Available since 2.0
Return to top
Show: