Module Example
Public Sub Main()
Dim value As String
Dim toDelete As Boolean = False
' Check whether the environment variable exists.
value = Environment.GetEnvironmentVariable("Test1")
' If necessary, create it.
If value Is Nothing Then
Environment.SetEnvironmentVariable("Test1", "Value1")
toDelete = True
' Now retrieve it.
value = Environment.GetEnvironmentVariable("Test1")
End If
' Display the value.
Console.WriteLine($"Test1: {value}")
Console.WriteLine()
' Confirm that the value can only be retrieved from the process
' environment block if running on a Windows system.
If Environment.OSVersion.Platform = PlatformID.Win32NT Then
Console.WriteLine("Attempting to retrieve Test1 from:")
For Each enumValue As EnvironmentVariableTarget In
[Enum].GetValues(GetType(EnvironmentVariableTarget))
value = Environment.GetEnvironmentVariable("Test1", enumValue)
Console.WriteLine($" {enumValue}: {If(value IsNot Nothing, "found", "not found")}")
Console.WriteLine()
End If
' If we've created it, now delete it.
If toDelete Then
Environment.SetEnvironmentVariable("Test1", Nothing)
' Confirm the deletion.
If Environment.GetEnvironmentVariable("Test1") = Nothing Then
Console.WriteLine("Test1 has been deleted.")
End If
End If
End Sub
End Module
' The example displays the following output if run on a Windows system:
' Test1: Value1
' Attempting to retrieve Test1 from:
' Process: found
' User: not found
' Machine: not found
' Test1 has been deleted.
' The example displays the following output if run on a Unix-based system:
' Test1: Value1
' Test1 has been deleted.
Remarks
Calling this method is equivalent to calling the
SetEnvironmentVariable(String, String, EnvironmentVariableTarget)
overload with a value of
EnvironmentVariableTarget.Process
for the
target
argument.
On non-Windows systems, calls to the
SetEnvironmentVariable(String, String)
method have no effect on any native libraries that are, or will be, loaded.
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.
public:
static void SetEnvironmentVariable(System::String ^ variable, System::String ^ value, EnvironmentVariableTarget target);
public static void SetEnvironmentVariable (string variable, string? value, EnvironmentVariableTarget target);
public static void SetEnvironmentVariable (string variable, string value, EnvironmentVariableTarget target);
static member SetEnvironmentVariable : string * string * EnvironmentVariableTarget -> unit
Public Shared Sub SetEnvironmentVariable (variable As String, value As String, target As EnvironmentVariableTarget)
Parameters
ArgumentException
variable
contains a zero-length string, an initial hexadecimal zero character (0x00), or an equal sign ("=").
The length of
variable
is greater than or equal to 32,767 characters.
target
is not a member of the
EnvironmentVariableTarget
enumeration.
target
is
Machine
or
User
, and the length of
variable
is greater than or equal to 255.
target
is
Process
and the length of
value
is greater than or equal to 32,767 characters.
An error occurred during the execution of this operation.
Examples
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. Because .NET on Unix-based systems does not support per-user and per-machine environment variables, only
SetEnvironmentVariable(String, String)
and
SetEnvironmentVariable(String, String, EnvironmentVariableTarget)
with a value of
EnvironmentVariableTarget.Process
successfully store an environment variable to the process environment block.
using System;
using System.Collections;
using Microsoft.Win32;
class Sample
public static void Main()
// Environment variable names for default, process, user, and machine targets.
string defaultEnvVar = nameof(defaultEnvVar);
string processEnvVar = nameof(processEnvVar);
string userEnvVar = nameof(userEnvVar);
string machineEnvVar = nameof(machineEnvVar);
string dft = nameof(dft);
string process = nameof(process);
string user = nameof(user);
string machine = nameof(machine);
// Set the environment variable for each target.
Console.WriteLine("Setting environment variables for each target...\n");
// The default target (the current process).
Environment.SetEnvironmentVariable(defaultEnvVar, dft);
// The current process.
Environment.SetEnvironmentVariable(processEnvVar, process,
EnvironmentVariableTarget.Process);
// The current user.
Environment.SetEnvironmentVariable(userEnvVar, user,
EnvironmentVariableTarget.User);
// The local machine.
Environment.SetEnvironmentVariable(machineEnvVar, machine,
EnvironmentVariableTarget.Machine);
// Define an array of environment variables.
string[] envVars = { defaultEnvVar,processEnvVar, userEnvVar, machineEnvVar };
// Try to get the environment variables from each target.
// The default (no specified target).
Console.WriteLine("Retrieving environment variables from the default target:");
foreach (var envVar in envVars)
var value = Environment.GetEnvironmentVariable(envVar) ?? "(none)";
Console.WriteLine($" {envVar}: {value}");
// The process block.
Console.WriteLine("\nRetrieving environment variables from the Process target:");
foreach (var envVar in envVars)
var value = Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.Process) ?? "(none)";
Console.WriteLine($" {envVar}: {value}");
// The user block.
Console.WriteLine("\nRetrieving environment variables from the User target:");
foreach (var envVar in envVars)
var value = Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.User) ?? "(none)";
Console.WriteLine($" {envVar}: {value}");
// The machine block.
Console.WriteLine("\nRetrieving environment variables from the Machine target:");
foreach (var envVar in envVars)
var value = Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.Machine) ?? "(none)";
Console.WriteLine($" {envVar}: {value}");
// Delete the environment variable for each target.
Console.WriteLine("\nDeleting environment variables for each target...\n");
// The default target (the current process).
Environment.SetEnvironmentVariable(defaultEnvVar, null);
// The current process.
Environment.SetEnvironmentVariable(processEnvVar, null,
EnvironmentVariableTarget.Process);
// The current user.
Environment.SetEnvironmentVariable(userEnvVar, null,
EnvironmentVariableTarget.User);
// The local machine.
Environment.SetEnvironmentVariable(machineEnvVar, null,
EnvironmentVariableTarget.Machine);
// The example displays the following output if run on a Windows system:
// Setting environment variables for each target...
// Retrieving environment variables from the default target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: user
// machineEnvVar: (none)
// Retrieving environment variables from the Process target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: user
// machineEnvVar: (none)
// Retrieving environment variables from the User target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: user
// machineEnvVar: (none)
// Retrieving environment variables from the Machine target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: (none)
// machineEnvVar: machine
// Deleting environment variables for each target...
// The example displays the following output if run on a Unix-based system:
// Setting environment variables for each target...
// Retrieving environment variables from the default target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: (none)
// machineEnvVar: (none)
// Retrieving environment variables from the Process target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: (none)
// machineEnvVar: (none)
// Retrieving environment variables from the User target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: (none)
// machineEnvVar: (none)
// Retrieving environment variables from the Machine target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: (none)
// machineEnvVar: (none)
// Deleting environment variables for each target...
module Sample
open System
// Environment variable names for default, process, user, and machine targets.
let rec defaultEnvVar = nameof defaultEnvVar
let rec processEnvVar = nameof processEnvVar
let rec userEnvVar = nameof userEnvVar
let rec machineEnvVar = nameof machineEnvVar
let rec dft = nameof dft
let rec proc = nameof proc
let rec user = nameof user
let rec machine = nameof machine
// Set the environment variable for each target.
printfn "Setting environment variables for each target...\n"
// The default target (the current process).
Environment.SetEnvironmentVariable(defaultEnvVar, dft)
// The current process.
Environment.SetEnvironmentVariable(processEnvVar, proc, EnvironmentVariableTarget.Process)
// The current user.
Environment.SetEnvironmentVariable(userEnvVar, user, EnvironmentVariableTarget.User)
// The local machine.
Environment.SetEnvironmentVariable(machineEnvVar, machine, EnvironmentVariableTarget.Machine)
// Define a list of environment variables.
let envVars = [ defaultEnvVar; processEnvVar; userEnvVar; machineEnvVar ]
// Try to get the environment variables from each target.
// The default (no specified target).
printfn "Retrieving environment variables from the default target:"
for envVar in envVars do
let value =
match Environment.GetEnvironmentVariable envVar with
| null -> "(none)"
| v -> v
printfn $" {envVar}: {value}"
// The process block.
printfn "\nRetrieving environment variables from the Process target:"
for envVar in envVars do
let value =
match Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.Process) with
| null -> "(none)"
| v -> v
printfn $" {envVar}: {value}"
// The user block.
printfn "\nRetrieving environment variables from the User target:"
for envVar in envVars do
let value =
match Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.User) with
| null -> "(none)"
| v -> v
printfn $" {envVar}: {value}"
// The machine block.
printfn "\nRetrieving environment variables from the Machine target:"
for envVar in envVars do
let value =
match Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.Machine) with
| null -> "(none)"
| v -> v
printfn $" {envVar}: {value}"
// Delete the environment variable for each target.
printfn "\nDeleting environment variables for each target...\n"
// The default target (the current process).
Environment.SetEnvironmentVariable(defaultEnvVar, null)
// The current process.
Environment.SetEnvironmentVariable(processEnvVar, null, EnvironmentVariableTarget.Process)
// The current user.
Environment.SetEnvironmentVariable(userEnvVar, null, EnvironmentVariableTarget.User)
// The local machine.
Environment.SetEnvironmentVariable(machineEnvVar, null, EnvironmentVariableTarget.Machine)
// The example displays the following output if run on a Windows system:
// Setting environment variables for each target...
// Retrieving environment variables from the default target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: user
// machineEnvVar: (none)
// Retrieving environment variables from the Process target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: user
// machineEnvVar: (none)
// Retrieving environment variables from the User target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: user
// machineEnvVar: (none)
// Retrieving environment variables from the Machine target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: (none)
// machineEnvVar: machine
// Deleting environment variables for each target...
// The example displays the following output if run on a Unix-based system:
// Setting environment variables for each target...
// Retrieving environment variables from the default target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: (none)
// machineEnvVar: (none)
// Retrieving environment variables from the Process target:
// defaultEnvVar: dft
// processEnvVar: process
// userEnvVar: (none)
// machineEnvVar: (none)
// Retrieving environment variables from the User target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: (none)
// machineEnvVar: (none)
// Retrieving environment variables from the Machine target:
// defaultEnvVar: (none)
// processEnvVar: (none)
// userEnvVar: (none)
// machineEnvVar: (none)
// Deleting environment variables for each target...
Imports System.Collections
Imports Microsoft.Win32
Module Sample
Public Sub Main()
' Environment variable names for default, process, user, and machine targets.
Dim defaultEnvVar As String = NameOf(defaultEnvVar)
Dim processEnvVar As String = NameOf(processEnvVar)
Dim userEnvVar As String = NameOf(userEnvVar)
Dim machineEnvVar As String = NameOf(machineEnvVar)
Dim dft As String = NameOf(dft)
Dim process As String = NameOf(process)
Dim user As String = NameOf(user)
Dim machine As String = NameOf(machine)
' Set the environment variable for each target.
Console.WriteLine("Setting environment variables for each target...")
' The default target (the current process).
Environment.SetEnvironmentVariable(defaultEnvVar, dft)
' The current process.
Environment.SetEnvironmentVariable(processEnvVar, process,
EnvironmentVariableTarget.Process)
' The current user.
Environment.SetEnvironmentVariable(userEnvVar, user,
EnvironmentVariableTarget.User)
' The local machine.
Environment.SetEnvironmentVariable(machineEnvVar, machine,
EnvironmentVariableTarget.Machine)
Console.WriteLine()
' Define an array of environment variables.
Dim envVars As String() = { defaultEnvVar, processEnvVar, userEnvVar, machineEnvVar }
' Try to get the environment variables from each target.
' The default (no specified target).
Console.WriteLine("Retrieving environment variables from the default target:")
For Each envVar in envVars
Dim value = Environment.GetEnvironmentVariable(envVar)
Console.WriteLine($" {envVar}: {If(value IsNot Nothing, value, "(none)")}")
Console.WriteLine()
' The process block.
Console.WriteLine("Retrieving environment variables from the Process target:")
For Each envVar in envVars
Dim value = Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.Process)
Console.WriteLine($" {envVar}: {If(value IsNot Nothing, value, "(none)")}")
Console.WriteLine()
' The user block.
Console.WriteLine("Retrieving environment variables from the User target:")
For Each envVar in envVars
Dim value = Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.User)
Console.WriteLine($" {envVar}: {value}")
Console.WriteLine()
' The machine block.
Console.WriteLine("Retrieving environment variables from the Machine target:")
For Each envVar in envVars
Dim value = Environment.GetEnvironmentVariable(envVar, EnvironmentVariableTarget.Machine)
Console.WriteLine($" {envVar}: {value}")
Console.WriteLine()
' Delete the environment variable for each target.
Console.WriteLine("Deleting environment variables for each target...")
' The default target (the current process).
Environment.SetEnvironmentVariable(defaultEnvVar, Nothing)
' The current process.
Environment.SetEnvironmentVariable(processEnvVar, Nothing,
EnvironmentVariableTarget.Process)
' The current user.
Environment.SetEnvironmentVariable(userEnvVar, Nothing,
EnvironmentVariableTarget.User)
' The local machine.
Environment.SetEnvironmentVariable(machineEnvVar, Nothing,
EnvironmentVariableTarget.Machine)
End Sub
End Module
' The example displays the following output if run on a Windows system:
' Setting environment variables for each target...
' Retrieving environment variables from the default target:
' defaultEnvVar: dft
' processEnvVar: process
' userEnvVar: user
' machineEnvVar: (none)
' Retrieving environment variables from the Process target:
' defaultEnvVar: dft
' processEnvVar: process
' userEnvVar: user
' machineEnvVar: (none)
' Retrieving environment variables from the User target:
' defaultEnvVar: (none)
' processEnvVar: (none)
' userEnvVar: user
' machineEnvVar: (none)
' Retrieving environment variables from the Machine target:
' defaultEnvVar: (none)
' processEnvVar: (none)
' userEnvVar: (none)
' machineEnvVar: machine
' Deleting environment variables for each target...
' The example displays the following output if run on a Unix-based system:
' Setting environment variables for each target...
' Retrieving environment variables from the default target:
' defaultEnvVar: dft
' processEnvVar: process
' userEnvVar: (none)
' machineEnvVar: (none)
' Retrieving environment variables from the Process target:
' defaultEnvVar: dft
' processEnvVar: process
' userEnvVar: (none)
' machineEnvVar: (none)
' Retrieving environment variables from the User target:
' defaultEnvVar: (none)
' processEnvVar: (none)
' userEnvVar: (none)
' machineEnvVar: (none)
' Retrieving environment variables from the Machine target:
' defaultEnvVar: (none)
' processEnvVar: (none)
' userEnvVar: (none)
' machineEnvVar: (none)
' Deleting environment variables for each target...
Remarks
The
SetEnvironmentVariable(String, String, EnvironmentVariableTarget)
method lets you define an environment variable that is available to the current process (the
Process
value). Environment variables that are unique to the current process environment block persist only until the process ends.
In addition, on Windows systems only, 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) and to all processes run by a user (the
EnvironmentVariableTarget.User
value). Per-machine and per-user environment variables are copied into the environment block of the current process.
On non-Windows systems, calls to the
SetEnvironmentVariable(String, String, EnvironmentVariableTarget)
method with a value of
EnvironmentVariableTarget.Machine
or
EnvironmentVariableTarget.User
are ignored.
On non-Windows systems, calls to the
SetEnvironmentVariable(String, String, EnvironmentVariableTarget)
method with a value of
EnvironmentVariableTarget.Process
have no effect on any native libraries that are, or will be, loaded.
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
argument 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.
EnvironmentVariableTarget.Machine and EnvironmentVariableTarget.User on Windows systems
If
target
is
EnvironmentVariableTarget.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.
GetEnvironmentVariable(String, EnvironmentVariableTarget)
GetEnvironmentVariables(EnvironmentVariableTarget)
EnvironmentVariableTarget
Applies to
