Environment::SetEnvironmentVariable Method (String^, String^)
Creates, modifies, or deletes an environment variable stored in the current process.
Assembly: mscorlib (in mscorlib.dll)
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.
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.
for full access to environment variables. Associated enumeration: Unrestricted
Available since 10
.NET Framework
Available since 2.0