Environment.SetEnvironmentVariable Metoda

Definicja

Tworzy, modyfikuje lub usuwa zmienną środowiskową.

Przeciążenia

SetEnvironmentVariable(String, String)

Tworzy, modyfikuje lub usuwa zmienną środowiskową przechowywaną w bieżącym procesie.

SetEnvironmentVariable(String, String, EnvironmentVariableTarget)

Tworzy, modyfikuje lub usuwa zmienną środowiskową przechowywaną w bieżącym procesie lub w kluczu rejestru systemu operacyjnego Windows zarezerwowanym dla bieżącego użytkownika lub komputera lokalnego.

SetEnvironmentVariable(String, String)

Źródło:
Environment.cs
Źródło:
Environment.cs
Źródło:
Environment.cs

Tworzy, modyfikuje lub usuwa zmienną środowiskową przechowywaną w bieżącym procesie.

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

Parametry

variable
String

Nazwa zmiennej środowiskowej.

value
String

Wartość do przypisania do variable.

Wyjątki

variable jest null.

variable zawiera ciąg o zerowej długości, początkowy znak szesnastkowy (0x00) lub znak równości ("=").

-lub-

Długość variable lub value jest większa lub równa 32 767 znaków.

-lub-

Wystąpił błąd podczas wykonywania tej operacji.

Obiekt wywołujący nie ma wymaganych uprawnień do wykonania tej operacji.

Przykłady

Poniższy przykład próbuje pobrać wartość zmiennej środowiskowej o nazwie Test1 z bloku środowiska przetwarzania. Jeśli zmienna nie istnieje, przykład tworzy zmienną i pobiera jej wartość. W przykładzie wyświetlana jest wartość zmiennej. W przypadku implementacji platformy .NET działających w systemach Windows wywołuje również metodę GetEnvironmentVariables(EnvironmentVariableTarget) z każdym elementem członkowskim wyliczenia EnvironmentVariableTarget w celu ustalenia, że zmienna może być pobierana tylko z bieżącego bloku środowiska procesu. (Implementacje platformy .NET w systemach podobnych do unix obsługują tylko zmienne w bloku środowiska przetwarzania). Na koniec, jeśli przykład utworzył zmienną, usuwa ją.

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.

Uwagi

Wywołanie tej metody jest równoważne wywołaniu przeciążenia SetEnvironmentVariable(String, String, EnvironmentVariableTarget) z wartością EnvironmentVariableTarget.Process dla argumentu target.

W systemach przypominających system Unix wywołania metody SetEnvironmentVariable(String, String) nie mają wpływu na biblioteki natywne, które są lub zostaną załadowane. (Z drugiej strony modyfikacje środowiska przetwarzania wprowadzone przez biblioteki natywne nie są widoczne przez osoby wywołujące zarządzane).

Jeśli argument value nie jest null, a zmienna środowiskowa o nazwie variable parametru nie istnieje, zmienna środowiskowa zostanie utworzona i przypisana zawartość value. Jeśli istnieje, jego wartość zostanie zmodyfikowana. Ponieważ zmienna środowiskowa jest zdefiniowana w bloku środowiskowym tylko bieżącego procesu, nie jest utrwalana po zakończeniu procesu.

Jeśli variable zawiera inny niż początkowy znak szesnastkowy, znaki przed znakiem zerowym są traktowane jako nazwa zmiennej środowiskowej, a wszystkie kolejne znaki są ignorowane.

Jeśli value zawiera inny niż początkowy znak szesnastkowy, znaki przed znakiem zerowym są przypisywane do zmiennej środowiskowej, a wszystkie kolejne znaki są ignorowane.

Jeśli value jest null (lub jest pusta w wersjach wcześniejszych niż .NET 9), a zmienna środowiskowa o nazwie variable istnieje, zmienna środowiskowa zostanie usunięta. Jeśli variable nie istnieje, nie wystąpi błąd, mimo że nie można wykonać operacji. value jest uważana za pustą w dowolnym z następujących warunków:

  • Jest to String.Empty.
  • Składa się z pojedynczego znaku, którego wartość to U+0000.

Zobacz też

Dotyczy

.NET 9 i inne wersje
Produkt Wersje
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

SetEnvironmentVariable(String, String, EnvironmentVariableTarget)

Źródło:
Environment.cs
Źródło:
Environment.cs
Źródło:
Environment.cs

Tworzy, modyfikuje lub usuwa zmienną środowiskową przechowywaną w bieżącym procesie lub w kluczu rejestru systemu operacyjnego Windows zarezerwowanym dla bieżącego użytkownika lub komputera lokalnego.

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

Parametry

variable
String

Nazwa zmiennej środowiskowej.

value
String

Wartość do przypisania do variable.

target
EnvironmentVariableTarget

Jedna z wartości wyliczenia, która określa lokalizację zmiennej środowiskowej.

Wyjątki

variable jest null.

variable zawiera ciąg o zerowej długości, początkowy znak szesnastkowy (0x00) lub znak równości ("=").

-lub-

Długość variable jest większa lub równa 32 767 znaków.

-lub-

target nie jest członkiem wyliczenia EnvironmentVariableTarget.

-lub-

target jest Machine lub User, a długość variable jest większa lub równa 255.

-lub-

target jest Process, a długość value jest większa lub równa 32 767 znaków.

-lub-

Wystąpił błąd podczas wykonywania tej operacji.

Obiekt wywołujący nie ma wymaganych uprawnień do wykonania tej operacji.

Przykłady

Poniższy przykład tworzy zmienne środowiskowe dla EnvironmentVariableTarget.Process, EnvironmentVariableTarget.Useri Machine obiektów docelowych, sprawdza, czy rejestr systemu operacyjnego zawiera zmienne środowiskowe użytkownika i komputera, a następnie usuwa zmienne środowiskowe. Ponieważ platforma .NET w systemach podobnych do systemu Unix nie obsługuje zmiennych środowiskowych dla poszczególnych użytkowników i maszyn, tylko SetEnvironmentVariable(String, String) i SetEnvironmentVariable(String, String, EnvironmentVariableTarget) z wartością EnvironmentVariableTarget.Process pomyślnie zapisać zmienną środowiskową do bloku środowiska procesu.

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

Uwagi

Metoda SetEnvironmentVariable(String, String, EnvironmentVariableTarget) umożliwia zdefiniowanie zmiennej środowiskowej dostępnej dla bieżącego procesu (wartość Process). Zmienne środowiskowe, które są unikatowe dla bieżącego bloku środowiska procesu, są utrwalane tylko do momentu zakończenia procesu.

Ponadto tylko w systemach Windows metoda SetEnvironmentVariable(String, String, EnvironmentVariableTarget) umożliwia zdefiniowanie zmiennej środowiskowej dostępnej dla wszystkich procesów uruchamianych na maszynie (wartość EnvironmentVariableTarget.Machine) i wszystkich procesów uruchamianych przez użytkownika (wartość EnvironmentVariableTarget.User). Zmienne środowiskowe dla maszyny i poszczególnych użytkowników są kopiowane do bloku środowiskowego bieżącego procesu.

W systemach przypominających system Unix wywołania metody SetEnvironmentVariable(String, String, EnvironmentVariableTarget) z wartością EnvironmentVariableTarget.Machine lub EnvironmentVariableTarget.User są ignorowane.

W systemach przypominających system Unix wywołania metody SetEnvironmentVariable(String, String, EnvironmentVariableTarget) z wartością EnvironmentVariableTarget.Process nie mają wpływu na żadne biblioteki natywne, które są lub zostaną załadowane. (Z drugiej strony modyfikacje środowiska przetwarzania wprowadzone przez biblioteki natywne nie są widoczne przez osoby wywołujące zarządzane).

Jeśli argument value nie jest null, a zmienna środowiskowa nazwana przez argument variable nie istnieje, zmienna środowiskowa zostanie utworzona i przypisana zawartość value. Jeśli istnieje, jego wartość zostanie zmodyfikowana.

Jeśli variable zawiera inny niż początkowy znak szesnastkowy, znaki przed znakiem zerowym są traktowane jako nazwa zmiennej środowiskowej, a wszystkie kolejne znaki są ignorowane.

Jeśli value zawiera inny niż początkowy znak szesnastkowy, znaki przed znakiem zerowym są przypisywane do zmiennej środowiskowej, a wszystkie kolejne znaki są ignorowane.

Jeśli value jest null (lub jest pusta w wersjach wcześniejszych niż .NET 9), a zmienna środowiskowa o nazwie variable istnieje, zmienna środowiskowa zostanie usunięta. value jest uważana za pustą w dowolnym z następujących warunków:

  • Jest to String.Empty.
  • Składa się z pojedynczego znaku, którego wartość to U+0000.

Jeśli variable nie istnieje, nie wystąpi błąd, chociaż nie można wykonać operacji. Należy zachować ostrożność, gdy target jest Machine, ponieważ można przypadkowo usunąć zmienną środowiskową, która ma wpływ na całą maszynę lokalną, a nie tylko bieżący proces lub użytkownik.

EnvironmentVariableTarget.Machine i EnvironmentVariableTarget.User w systemach Windows

Jeśli target jest EnvironmentVariableTarget.User, zmienna środowiskowa jest przechowywana w kluczu HKEY_CURRENT_USER\Environment rejestru komputera lokalnego. Jest on również kopiowany do wystąpień Eksploratora plików, które są uruchomione jako bieżący użytkownik. Zmienna środowiskowa jest następnie dziedziczona przez wszelkie nowe procesy uruchamiane przez użytkownika z Eksploratora plików.

Podobnie, jeśli target jest EnvironmentVariableTarget.Machine, zmienna środowiskowa jest przechowywana w kluczu HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Control\Session Manager\Environment rejestru komputera lokalnego. Jest on również kopiowany do wszystkich wystąpień Eksploratora plików. Zmienna środowiskowa jest następnie dziedziczona przez wszystkie nowe procesy uruchamiane z Eksploratora plików.

Jeśli target jest User lub Machine, inne aplikacje są powiadamiane o operacji zestawu przez komunikat WM_SETTINGCHANGE systemu Windows.

Jeśli target jest EnvironmentVariableTarget.User lub EnvironmentVariableTarget.Machine, zalecamy, aby długość value być mniejsza niż 2048 znaków.

Zobacz też

Dotyczy

.NET 9 i inne wersje
Produkt Wersje
.NET Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 2.0, 2.1