Environment.SetEnvironmentVariable Method (String, String, EnvironmentVariableTarget)

 

Creates, modifies, or deletes an environment variable stored in the current process or in the Windows operating system registry key reserved for the current user or local machine.

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

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

Parameters

variable
Type: System.String

The name of an environment variable.

value
Type: System.String

A value to assign to variable.

target
Type: System.EnvironmentVariableTarget

One of the enumeration values that specifies the location of the environment 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 is greater than or equal to 32,767 characters.

-or-

target is not a member of the EnvironmentVariableTarget enumeration.

-or-

target is Machine or User, and the length of variable is greater than or equal to 255.

-or-

target is Process and the length of 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.

The SetEnvironmentVariable(String, String, EnvironmentVariableTarget) method lets you define an environment variable that is available to all processes that run on a machine (the EnvironmentVariableTarget.Machine value), to all processes run by a user (the EnvironmentVariableTarget.User value), or to the current process (the Process value). Per-machine and per-user environment variables are copied into the environment block of the current process. However, environment variables that are unique to the current process environment block persist only until the process ends.

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.

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. 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.

If variable does not exist, no error occurs although the operation cannot be performed. Be careful when target is Machine, because you can accidentally delete an environment variable that affects your entire local machine, not just the current process or user.

If target is User, the environment variable is stored in the HKEY_CURRENT_USER\Environment key of the local computer's registry. It is also copied to instances of File Explorer that are running as the current user. The environment variable is then inherited by any new processes that the user launches from File Explorer.

Similarly, if target is EnvironmentVariableTarget.Machine, the environment variable is stored in the HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Session Manager\Environment key of the local computer's registry. It is also copied to all instances of File Explorer. The environment variable is then inherited by any new processes that are launched from File Explorer.

If target is User or Machine, other applications are notified of the set operation by a Windows WM_SETTINGCHANGE message.

If target is EnvironmentVariableTarget.User or EnvironmentVariableTarget.Machine, we recommend that the length of value be less than 2048 characters.

The following example creates environment variables for the EnvironmentVariableTarget.Process, EnvironmentVariableTarget.User, and Machine targets, checks whether the operating system registry contains the user and machine environment variables, then deletes the environment variables.

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

EnvironmentPermission

for full access to environment variables. Associated enumeration: PermissionState.Unrestricted

.NET Framework
Available since 2.0
Return to top
Show: