From b7c963d4690a38975a5772177656a5c3032112c4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 15 Mar 2024 10:00:48 -0700 Subject: [PATCH 1/3] add note about native settings --- xml/System/Environment.xml | 42 ++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/xml/System/Environment.xml b/xml/System/Environment.xml index 73563fd60e4..261e51299de 100644 --- a/xml/System/Environment.xml +++ b/xml/System/Environment.xml @@ -556,7 +556,7 @@ Invalid argument 4.2.0.0 - Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and optional exception information is included in error reporting to Microsoft. For Unix-like systems, the message, alongside the stack trace, is written to the standard error stream. + Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and optional exception information is included in error reporting to Microsoft. For Unix-based systems, the message, alongside the stack trace, is written to the standard error stream. @@ -618,7 +618,7 @@ Invalid argument A message that explains why the process was terminated, or if no explanation is provided. - Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message is included in error reporting to Microsoft. For Unix-like systems, the message, alongside the stack trace, is written to the standard error stream. + Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message is included in error reporting to Microsoft. For Unix-based systems, the message, alongside the stack trace, is written to the standard error stream. method to terminate your application if the state of your application is damaged beyond repair, and executing your application's `try`/`finally` blocks and finalizers will corrupt program resources. Calling the `Environment.FailFast` method to terminate execution of an application running in the Visual Studio debugger throws an and automatically triggers the [fatalExecutionEngineError managed debugging assistant (MDA)](/dotnet/framework/debug-trace-profile/fatalexecutionengineerror-mda). ## Examples - The following example writes a log entry to the Windows Application event log when running under Windows, or writes the error message to the standard error stream when running under a Unix-like system, and terminates the current process. + The following example writes a log entry to the Windows Application event log when running under Windows, or writes the error message to the standard error stream when running under a Unix-based system, and terminates the current process. :::code language="csharp" source="~/snippets/csharp/System/Environment/FailFast/ff.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/FailFast/ff.fs" id="Snippet1"::: @@ -704,7 +704,7 @@ Calling the `Environment.FailFast` method to terminate execution of an applicati A message that explains why the process was terminated, or if no explanation is provided. An exception that represents the error that caused the termination. This is typically the exception in a block. - Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and exception information is included in error reporting to Microsoft. For Unix-like systems, the message alongside the stack trace is written to the standard error stream. + Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and exception information is included in error reporting to Microsoft. For Unix-based systems, the message alongside the stack trace is written to the standard error stream. method overload. @@ -1041,26 +1041,29 @@ The following example creates environment variables for the . + +The names and values for the environment variables are stored as key-value pairs in the returned . + +> [!NOTE] +> In-process environment modifications made by native libraries aren't seen by managed callers. ### On Windows systems On Windows systems, the `GetEnvironmentVariables` method returns the following environment variables: - All per-machine environment variables that are defined at the time the process is created, along with their values. - - All per-user environment variables that are defined at the time the process is created, along with their values. - - Any variables inherited from the parent process from which the .NET application was launched or added to the process block while the process is running. Environment variables are added while the process is running by calling either the method or the method with a `target` value of . -### On non-Windows systems +### On Unix-based systems -On non-Windows systems, the `GetEnvironmentVariables` method retrieves the name and value of all environment variables that are inherited from the parent process that launched the `dotnet` process or that are defined within the scope of the `dotnet` process itself. Once the `dotnet` process ends, these latter environment variables cease to exist. +On Unix-based systems, the `GetEnvironmentVariables` method retrieves the name and value of all environment variables that are inherited from the parent process that launched the `dotnet` process or that are defined within the scope of the `dotnet` process itself. Once the `dotnet` process ends, these latter environment variables cease to exist. .NET running on Unix-based systems does not support per-machine or per-user environment variables. ## Examples - The following example demonstrates the method. + +The following example demonstrates the method. :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Environment.GetEnvironmentVariables/CPP/getenvironmentvariables.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariables/getenvironmentvariables.cs" id="Snippet1"::: @@ -1130,15 +1133,18 @@ On non-Windows systems, the `GetEnvironmentVariables` method retrieves the name The names and values of the environment variables are stored as key/value pairs in the returned object. +> [!NOTE] +> In-process environment modifications made by native libraries aren't seen by managed callers. + ### On Windows systems On Windows systems, the `target` parameter specifies whether the source is the current process, the registry key for the current user, or the registry key for the local machine. -### On non-Windows systems +### On Unix-based systems -On non-Windows systems, only a `target` value of is supported. Per-process environment variables are inherited from the parent process (typically the shell) used to launch the `dotnet` process or are defined within the scope of the `dotnet` process itself. Once the dotnet process ends, these latter environment variables cease to exist. +On Unix-based systems, only a `target` value of is supported. Per-process environment variables are inherited from the parent process (typically the shell) used to launch the `dotnet` process or are defined within the scope of the `dotnet` process itself. Once the dotnet process ends, these latter environment variables cease to exist. -Per-machine and per-user environment variables are not supported. A `target` value of or returns an empty array. +Per-machine and per-user environment variables aren't supported. A `target` value of or returns an empty array. ## Examples @@ -2004,7 +2010,7 @@ If the executable is renamed or deleted before this property is first accessed, ## Remarks Calling this method is equivalent to calling the overload with a value of for the `target` argument. - On non-Windows systems, calls to the method have no effect on any native libraries that are, or will be, loaded. + On Unix-based systems, calls to the 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. @@ -2116,9 +2122,9 @@ The method lets you define an environment variable that is available to all processes that run on a machine (the value) and to all processes run by a user (the 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 method with a value of or are ignored. +On Unix-based systems, calls to the method with a value of or are ignored. -On non-Windows systems, calls to the method with a value of have no effect on any native libraries that are, or will be, loaded. +On Unix-based systems, calls to the method with a value of 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. From afca483e3779ed0df1493b26f4419e5659127995 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 15 Mar 2024 10:04:17 -0700 Subject: [PATCH 2/3] unix-like --- xml/System/Environment.xml | 40 +++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/xml/System/Environment.xml b/xml/System/Environment.xml index 261e51299de..9ab005590f0 100644 --- a/xml/System/Environment.xml +++ b/xml/System/Environment.xml @@ -556,7 +556,7 @@ Invalid argument 4.2.0.0 - Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and optional exception information is included in error reporting to Microsoft. For Unix-based systems, the message, alongside the stack trace, is written to the standard error stream. + Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and optional exception information is included in error reporting to Microsoft. For Unix-like systems, the message, alongside the stack trace, is written to the standard error stream. @@ -618,7 +618,7 @@ Invalid argument A message that explains why the process was terminated, or if no explanation is provided. - Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message is included in error reporting to Microsoft. For Unix-based systems, the message, alongside the stack trace, is written to the standard error stream. + Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message is included in error reporting to Microsoft. For Unix-like systems, the message, alongside the stack trace, is written to the standard error stream. method to terminate your application if the state of your application is damaged beyond repair, and executing your application's `try`/`finally` blocks and finalizers will corrupt program resources. Calling the `Environment.FailFast` method to terminate execution of an application running in the Visual Studio debugger throws an and automatically triggers the [fatalExecutionEngineError managed debugging assistant (MDA)](/dotnet/framework/debug-trace-profile/fatalexecutionengineerror-mda). ## Examples - The following example writes a log entry to the Windows Application event log when running under Windows, or writes the error message to the standard error stream when running under a Unix-based system, and terminates the current process. + The following example writes a log entry to the Windows Application event log when running under Windows, or writes the error message to the standard error stream when running under a Unix-like system, and terminates the current process. :::code language="csharp" source="~/snippets/csharp/System/Environment/FailFast/ff.cs" id="Snippet1"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/FailFast/ff.fs" id="Snippet1"::: @@ -704,7 +704,7 @@ Calling the `Environment.FailFast` method to terminate execution of an applicati A message that explains why the process was terminated, or if no explanation is provided. An exception that represents the error that caused the termination. This is typically the exception in a block. - Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and exception information is included in error reporting to Microsoft. For Unix-based systems, the message alongside the stack trace is written to the standard error stream. + Immediately terminates the process before reporting an error message. For Windows, the error message is written to the Windows Application event log, and the message and exception information is included in error reporting to Microsoft. For Unix-like systems, the message alongside the stack trace is written to the standard error stream. method overload. @@ -954,13 +954,13 @@ The following example attempts to retrieve the value of an environment variable The name of an environment variable. - One of the values. Only is supported on .NET running on Unix-based systems. + One of the values. Only is supported on .NET running on Unix-like systems. Retrieves the value of an environment variable from the current process or from the Windows operating system registry key for the current user or local machine. The value of the environment variable specified by the and parameters, or if the environment variable is not found. For more information about this API, see Supplemental API remarks for Environment.GetEnvironmentVariable. , , and 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 and with a value of successfully store an environment variable to the process environment block. +The following example creates environment variables for the , , and targets, checks whether the operating system registry contains the user and machine environment variables, then deletes the environment variables. Because .NET on Unix-like systems does not support per-user and per-machine environment variables, only and with a value of successfully store an environment variable to the process environment block. :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/gsev.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/gsev.fs"::: @@ -1055,11 +1055,11 @@ On Windows systems, the `GetEnvironmentVariables` method returns the following e - All per-user environment variables that are defined at the time the process is created, along with their values. - Any variables inherited from the parent process from which the .NET application was launched or added to the process block while the process is running. Environment variables are added while the process is running by calling either the method or the method with a `target` value of . -### On Unix-based systems +### On Unix-like systems -On Unix-based systems, the `GetEnvironmentVariables` method retrieves the name and value of all environment variables that are inherited from the parent process that launched the `dotnet` process or that are defined within the scope of the `dotnet` process itself. Once the `dotnet` process ends, these latter environment variables cease to exist. +On Unix-like systems, the `GetEnvironmentVariables` method retrieves the name and value of all environment variables that are inherited from the parent process that launched the `dotnet` process or that are defined within the scope of the `dotnet` process itself. Once the `dotnet` process ends, these latter environment variables cease to exist. -.NET running on Unix-based systems does not support per-machine or per-user environment variables. +.NET running on Unix-like systems does not support per-machine or per-user environment variables. ## Examples @@ -1123,7 +1123,7 @@ The following example demonstrates the - One of the values. Only is supported on .NET running on Unix-based systems. + One of the values. Only is supported on .NET running on Unix-like systems. Retrieves all environment variable names and their values from the current process, or from the Windows operating system registry key for the current user or local machine. A dictionary that contains all environment variable names and their values from the source specified by the parameter; otherwise, an empty dictionary if no environment variables are found. @@ -1140,15 +1140,15 @@ The names and values of the environment variables are stored as key/value pairs On Windows systems, the `target` parameter specifies whether the source is the current process, the registry key for the current user, or the registry key for the local machine. -### On Unix-based systems +### On Unix-like systems -On Unix-based systems, only a `target` value of is supported. Per-process environment variables are inherited from the parent process (typically the shell) used to launch the `dotnet` process or are defined within the scope of the `dotnet` process itself. Once the dotnet process ends, these latter environment variables cease to exist. +On Unix-like systems, only a `target` value of is supported. Per-process environment variables are inherited from the parent process (typically the shell) used to launch the `dotnet` process or are defined within the scope of the `dotnet` process itself. Once the dotnet process ends, these latter environment variables cease to exist. Per-machine and per-user environment variables aren't supported. A `target` value of or returns an empty array. ## Examples -The following example creates environment variables for the , , and 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 and with a value of successfully store an environment variable to the process environment block. +The following example creates environment variables for the , , and targets, checks whether the operating system registry contains the user and machine environment variables, then deletes the environment variables. Because .NET on Unix-like systems does not support per-user and per-machine environment variables, only and with a value of successfully store an environment variable to the process environment block. :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/gsev.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/gsev.fs"::: @@ -2010,7 +2010,7 @@ If the executable is renamed or deleted before this property is first accessed, ## Remarks Calling this method is equivalent to calling the overload with a value of for the `target` argument. - On Unix-based systems, calls to the method have no effect on any native libraries that are, or will be, loaded. + On Unix-like systems, calls to the 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. @@ -2028,7 +2028,7 @@ If the executable is renamed or deleted before this property is first accessed, ## Examples -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. For .NET implementations running on Windows systems, it also calls the method with each member of the enumeration to establish that the variable can be retrieved only from the current process environment block. (.NET implementations on Unix-based systems only support variables in the process environment block.) Finally, if the example created the variable, it deletes it. +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. For .NET implementations running on Windows systems, it also calls the method with each member of the enumeration to establish that the variable can be retrieved only from the current process environment block. (.NET implementations on Unix-like systems only support variables in the process environment block.) Finally, if the example created the variable, it deletes it. :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/getenvironmentvariableex1.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/getenvironmentvariableex1.fs"::: @@ -2122,9 +2122,9 @@ The method lets you define an environment variable that is available to all processes that run on a machine (the value) and to all processes run by a user (the value). Per-machine and per-user environment variables are copied into the environment block of the current process. -On Unix-based systems, calls to the method with a value of or are ignored. +On Unix-like systems, calls to the method with a value of or are ignored. -On Unix-based systems, calls to the method with a value of have no effect on any native libraries that are, or will be, loaded. +On Unix-like systems, calls to the method with a value of 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. @@ -2154,7 +2154,7 @@ If `target` is , , and 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 and with a value of successfully store an environment variable to the process environment block. +The following example creates environment variables for the , , and targets, checks whether the operating system registry contains the user and machine environment variables, then deletes the environment variables. Because .NET on Unix-like systems does not support per-user and per-machine environment variables, only and with a value of successfully store an environment variable to the process environment block. :::code language="csharp" source="~/snippets/csharp/System/Environment/GetEnvironmentVariable/gsev.cs"::: :::code language="fsharp" source="~/snippets/fsharp/System/Environment/GetEnvironmentVariable/gsev.fs"::: From 2fd6c8ce33e7a2d2e07c9282bcbf59d692bc31a0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 15 Mar 2024 17:51:30 -0700 Subject: [PATCH 3/3] clarify that it's unix-like systems --- xml/System/Environment.xml | 43 ++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 23 deletions(-) diff --git a/xml/System/Environment.xml b/xml/System/Environment.xml index 9ab005590f0..a4a089bac37 100644 --- a/xml/System/Environment.xml +++ b/xml/System/Environment.xml @@ -1044,9 +1044,6 @@ The following example creates environment variables for the . -> [!NOTE] -> In-process environment modifications made by native libraries aren't seen by managed callers. - ### On Windows systems On Windows systems, the `GetEnvironmentVariables` method returns the following environment variables: @@ -1061,6 +1058,9 @@ On Unix-like systems, the `GetEnvironmentVariables` method retrieves the name an .NET running on Unix-like systems does not support per-machine or per-user environment variables. +> [!NOTE] +> On Unix-like systems, in-process environment modifications made by native libraries aren't seen by managed callers. + ## Examples The following example demonstrates the method. @@ -1133,9 +1133,6 @@ The following example demonstrates the object. -> [!NOTE] -> In-process environment modifications made by native libraries aren't seen by managed callers. - ### On Windows systems On Windows systems, the `target` parameter specifies whether the source is the current process, the registry key for the current user, or the registry key for the local machine. @@ -1146,6 +1143,9 @@ On Unix-like systems, only a `target` value of or returns an empty array. +> [!NOTE] +> On Unix-like systems, in-process environment modifications made by native libraries aren't seen by managed callers. + ## Examples The following example creates environment variables for the , , and targets, checks whether the operating system registry contains the user and machine environment variables, then deletes the environment variables. Because .NET on Unix-like systems does not support per-user and per-machine environment variables, only and with a value of successfully store an environment variable to the process environment block. @@ -2008,9 +2008,10 @@ If the executable is renamed or deleted before this property is first accessed, overload with a value of for the `target` argument. - On Unix-like systems, calls to the method have no effect on any native libraries that are, or will be, loaded. + On Unix-like systems, calls to the method have no effect on any native libraries that are, or will be, loaded. (Conversely, in-process environment modifications made by native libraries aren't seen by managed callers.) 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. @@ -2020,11 +2021,9 @@ If the executable is renamed or deleted before this property is first accessed, 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 . - -- It consists of a single character whose value is U+0000. +- It is `null`. +- It is . +- It consists of a single character whose value is U+0000. ## Examples @@ -2124,33 +2123,31 @@ In addition, on Windows systems only, the method with a value of or are ignored. -On Unix-like systems, calls to the method with a value of have no effect on any native libraries that are, or will be, loaded. +On Unix-like systems, calls to the method with a value of have no effect on any native libraries that are, or will be, loaded. (Conversely, in-process environment modifications made by native libraries aren't seen by managed callers.) - 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 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 `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` 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: +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 . - - 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 , because you can accidentally delete an environment variable that affects your entire local machine, not just the current process or user. +If `variable` does not exist, no error occurs although the operation cannot be performed. Be careful when `target` is , 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 , 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 , 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. +Similarly, if `target` is , 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 or , other applications are notified of the set operation by a Windows `WM_SETTINGCHANGE` message. +If `target` is or , other applications are notified of the set operation by a Windows `WM_SETTINGCHANGE` message. - If `target` is or , we recommend that the length of `value` be less than 2048 characters. +If `target` is or , we recommend that the length of `value` be less than 2048 characters. ## Examples