This documentation is archived and is not being maintained.

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

ExceptionCondition
ArgumentNullException

variable is a null reference (Nothing in Visual Basic).

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.

If the value parameter is not empty and the environment variable named by the variable parameter does not exist, the environment variable is created and assigned the contents of value. Solely for the purposes of this operation, value is considered empty if it is a null reference (Nothing in Visual Basic), contains a zero-length string, or contains an initial hexadecimal zero character (0x00).

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. Exercise caution when target is Machine because you can 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 Windows registry key reserved for the current user. It is also copied to instances of Windows Explorer that are running as the current user. The environment variable is then inherited by any new processes that the user launches from Windows Explorer.

Similarly, if target is Machine, the environment variable is stored in the Windows registry key reserved for the local computer. It is also copied to all instances of Windows Explorer. The environment variable is then inherited by any new processes that are launched from Windows Explorer.

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

If target is User or Machine, it is recommended that the length of value be less than 2048 characters.

The following example creates environment variables for the Process, 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.

.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Show: