Environment.SetEnvironmentVariable 方法

定义

命名空间:

System

程序集:

System.Runtime.dll

创建、修改或删除环境变量。

重载

SetEnvironmentVariable(String, String)	创建、修改或删除存储在当前进程中的环境变量。
SetEnvironmentVariable(String, String, EnvironmentVariableTarget)	创建、修改或删除存储在当前进程或为当前用户或本地计算机保留的 Windows 操作系统注册表项中的环境变量。

SetEnvironmentVariable(String, String)

Source:

Environment.cs

创建、修改或删除存储在当前进程中的环境变量。

C#

public static void SetEnvironmentVariable (string variable, string? value);

参数

variable

String

环境变量的名称。

value

String

要分配给 variable的值。

例外

ArgumentNullException

variable null。

ArgumentException

variable 包含零长度字符串、初始十六进制零字符（0x00）或等号（“=”）。

-或-

variable 或 value 的长度大于或等于 32,767 个字符。

-或-

执行此操作期间发生错误。

SecurityException

调用方没有执行此操作所需的权限。

示例

以下示例尝试从进程环境块中检索名为 Test1 的环境变量的值。 如果该变量不存在，该示例将创建变量并检索其值。 该示例显示变量的值。 对于在 Windows 系统上运行的 .NET 实现，它还调用具有 EnvironmentVariableTarget 枚举的每个成员的 GetEnvironmentVariables(EnvironmentVariableTarget) 方法，以建立变量只能从当前进程环境块中检索。 （类似 Unix 的系统上的 .NET 实现仅支持进程环境块中的变量。最后，如果示例创建了变量，则会将其删除。

C#

using System;

public class Example
{
   public static void Main()
   {
      string value;
      bool toDelete = false;

      // Check whether the environment variable exists.
      value = Environment.GetEnvironmentVariable("Test1");
      // If necessary, create it.
      if (value == null)
      {
         Environment.SetEnvironmentVariable("Test1", "Value1");
         toDelete = true;

         // Now retrieve it.
         value = Environment.GetEnvironmentVariable("Test1");
      }
      // Display the value.
      Console.WriteLine($"Test1: {value}\n");

      // 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)
      {
         Console.WriteLine("Attempting to retrieve Test1 from:");
         foreach (EnvironmentVariableTarget enumValue in
                           Enum.GetValues(typeof(EnvironmentVariableTarget))) {
            value = Environment.GetEnvironmentVariable("Test1", enumValue);
            Console.WriteLine($"   {enumValue}: {(value != null ? "found" : "not found")}");
         }
         Console.WriteLine();
      }

      // If we've created it, now delete it.
      if (toDelete) {
         Environment.SetEnvironmentVariable("Test1", null);
         // Confirm the deletion.
         if (Environment.GetEnvironmentVariable("Test1") == null)
            Console.WriteLine("Test1 has been deleted.");
      }
   }
}
// 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.

注解

调用此方法等效于调用具有 target 参数 EnvironmentVariableTarget.Process 值的 SetEnvironmentVariable(String, String, EnvironmentVariableTarget) 重载。

在类似 Unix 的系统上，对 SetEnvironmentVariable(String, String) 方法的调用对任何本机库（或将被加载）没有任何影响。 （相反，托管调用方不会看到本机库进行的进程内环境修改。

如果未 nullvalue 参数，并且 variable 参数命名的环境变量不存在，则会创建环境变量并为其分配 value的内容。 如果存在，则修改其值。 由于环境变量仅在当前进程的环境块中定义，因此在进程结束之后不会保留该变量。

如果 variable 包含非初始十六进制零字符，则零字符之前的字符被视为环境变量名称，并忽略所有后续字符。

如果 value 包含非初始十六进制零字符，则零字符前的字符将分配给环境变量，并忽略所有后续字符。

如果 valuenull（或 .NET 9 之前的版本中为空），并且存在由 variable 命名的环境变量，则会删除该环境变量。 如果 variable 不存在，即使无法执行操作，也不会发生错误。 在以下任一条件下，value 被视为空：

• 这是 String.Empty。
• 它包含一个字符，其值为 U+0000。

另请参阅

• GetEnvironmentVariable(String)
• GetEnvironmentVariables()

SetEnvironmentVariable(String, String, EnvironmentVariableTarget)

Source:

Environment.cs

创建、修改或删除存储在当前进程或为当前用户或本地计算机保留的 Windows 操作系统注册表项中的环境变量。

C#

public static void SetEnvironmentVariable (string variable, string? value, EnvironmentVariableTarget target);

参数

variable

String

环境变量的名称。

value

String

要分配给 variable的值。

target

EnvironmentVariableTarget

指定环境变量位置的枚举值之一。

例外

ArgumentNullException

variable null。

ArgumentException

variable 包含零长度字符串、初始十六进制零字符（0x00）或等号（“=”）。

-或-

variable 长度大于或等于 32,767 个字符。

-或-

target 不是 EnvironmentVariableTarget 枚举的成员。

-或-

target 是 Machine 或 User，并且 variable 长度大于或等于 255。

-或-

target Process，value 长度大于或等于 32,767 个字符。

-或-

执行此操作期间发生错误。

SecurityException

调用方没有执行此操作所需的权限。

示例

以下示例为 EnvironmentVariableTarget.Process、EnvironmentVariableTarget.User和 Machine 目标创建环境变量，检查操作系统注册表是否包含用户和计算机环境变量，然后删除环境变量。 由于类似 Unix 的系统上的 .NET 不支持每用户和每台计算机环境变量，因此仅 SetEnvironmentVariable(String, String) 和 SetEnvironmentVariable(String, String, EnvironmentVariableTarget)，其值为 EnvironmentVariableTarget.Process 成功将环境变量存储到进程环境块。

C#

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

注解

使用 SetEnvironmentVariable(String, String, EnvironmentVariableTarget) 方法可以定义可用于当前进程（Process 值）的环境变量。 当前进程环境块唯一的环境变量仅在进程结束之前保留。

此外，仅在 Windows 系统上，SetEnvironmentVariable(String, String, EnvironmentVariableTarget) 方法允许你定义一个环境变量，该环境变量可用于计算机上运行的所有进程（EnvironmentVariableTarget.Machine 值）以及用户运行的所有进程（EnvironmentVariableTarget.User 值）。 每台计算机和每用户环境变量将复制到当前进程的环境块中。

在类似 Unix 的系统上，将忽略对具有 EnvironmentVariableTarget.Machine 或 EnvironmentVariableTarget.User 值的 SetEnvironmentVariable(String, String, EnvironmentVariableTarget) 方法的调用。

在类似 Unix 的系统上，对具有 EnvironmentVariableTarget.Process 值的 SetEnvironmentVariable(String, String, EnvironmentVariableTarget) 方法的调用对任何本机库（或将加载）没有任何影响。 （相反，托管调用方不会看到本机库进行的进程内环境修改。

如果未 nullvalue 参数，并且由 variable 参数命名的环境变量不存在，则会创建环境变量并为其分配 value的内容。 如果存在，则修改其值。

如果 variable 包含非初始十六进制零字符，则零字符之前的字符被视为环境变量名称，并忽略所有后续字符。

如果 value 包含非初始十六进制零字符，则零字符前的字符将分配给环境变量，并忽略所有后续字符。

如果 valuenull（或 .NET 9 之前的版本中为空），并且存在由 variable 命名的环境变量，则会删除该环境变量。 在以下任一条件下，value 被视为空：

• 这是 String.Empty。
• 它包含一个字符，其值为 U+0000。

如果 variable 不存在，则无法执行该操作，但不会发生错误。 当 targetMachine时要小心，因为可能会意外删除影响整个本地计算机的环境变量，而不仅仅是当前进程或用户。

Windows 系统上的 EnvironmentVariableTarget.Machine 和 EnvironmentVariableTarget.User

如果 targetEnvironmentVariableTarget.User，则环境变量存储在本地计算机的注册表的 HKEY_CURRENT_USER\Environment 键中。 它还复制到作为当前用户运行的文件资源管理器实例。 然后，环境变量由用户从文件资源管理器启动的任何新进程继承。

同样，如果 targetEnvironmentVariableTarget.Machine，则环境变量存储在本地计算机的注册表的 HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Session Manager\Environment 键中。 它还会复制到文件资源管理器的所有实例。 然后，环境变量由从文件资源管理器启动的任何新进程继承。

如果 targetUser 或 Machine，则 Windows WM_SETTINGCHANGE 消息会通知其他应用程序设置操作。

如果 targetEnvironmentVariableTarget.User 或 EnvironmentVariableTarget.Machine，我们建议 value 长度小于 2048 个字符。

另请参阅

• GetEnvironmentVariable(String, EnvironmentVariableTarget)
• GetEnvironmentVariables(EnvironmentVariableTarget)
• EnvironmentVariableTarget