From 3e97a1258ad4543e2a8de455bdf6278690fe3f07 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 8 Nov 2023 17:21:47 -0800 Subject: [PATCH 1/2] update per .net 8 --- xml/System.Diagnostics/ProcessStartInfo.xml | 548 ++++++++++---------- xml/System.Linq/Enumerable.xml | 8 + 2 files changed, 281 insertions(+), 275 deletions(-) diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index 58093f12867..a41ab5b979c 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -56,35 +56,35 @@ Specifies a set of values that are used when you start a process. - is used together with the component. When you start a process using the class, you have access to process information in addition to that available when attaching to a running process. - - You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - - In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. - - Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. - - Set the property to specify whether to start the process by using the operating system shell. If is set to `false`, the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to `true`. - + is used together with the component. When you start a process using the class, you have access to process information in addition to that available when attaching to a running process. + + You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + + In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. + + Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. + + Set the property to specify whether to start the process by using the operating system shell. If is set to `false`, the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to `true`. + You can change the value of any property up to the time that the process starts. After you start the process, changing these values has no effect. - + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] - + > [!NOTE] -> This class contains a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). - - - -## Examples - The following code example demonstrates how to use the class to start Internet Explorer. The destination URLs are provided as arguments. - +> This class contains a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). + + + +## Examples + The following code example demonstrates how to use the class to start Internet Explorer. The destination URLs are provided as arguments. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstartstatic.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb"::: + ]]> @@ -134,13 +134,13 @@ Initializes a new instance of the class without specifying a file name with which to start the process. - property before you start the process. The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - - Optionally, you can also set other properties before you start the process. The property supplies actions to take, such as "print", with the file indicated in the property. The property supplies a way to pass command-line arguments to the file when the system opens it. - + property before you start the process. The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + + Optionally, you can also set other properties before you start the process. The property supplies actions to take, such as "print", with the file indicated in the property. The property supplies a way to pass command-line arguments to the file when the system opens it. + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] ]]> @@ -185,13 +185,13 @@ An application or document with which to start a process. Initializes a new instance of the class and specifies a file name such as an application or document with which to start the process. - property after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. - + property after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] ]]> @@ -264,15 +264,15 @@ Command-line arguments to pass to the application when the process starts. Initializes a new instance of the class, specifies an application file name with which to start the process, and specifies a set of command-line arguments to pass to the application. - or properties after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. - + or properties after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] - + ]]> @@ -306,7 +306,7 @@ A collection of command-line arguments. property are independent of one another and **only one of them can be used at the same time**. The main difference between both APIs is that `ArgumentList` takes care of escaping the provided arguments and **internally** builds a single string that is passed to operating system when calling `Process.Start(info)`. So if you are not sure how to properly escape your arguments, you should choose `ArgumentList` over . [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] @@ -436,31 +436,31 @@ info.Arguments = "/c dir ""C:\Program Files\dotnet""" Gets or sets the set of command-line arguments to use when starting the application. - A single string containing the arguments to pass to the target application specified in the property. The default is an empty string (""). + A single string containing the arguments to pass to the target application specified in the property. The default is an empty string (""). must not contain any elements. - + `Arguments` and , which is supported starting with .NET Core 2.1 and .NET Standard 2.1, are independent of one another. That is, the string assigned to the `Arguments` property does not populate the collection, and the members of the collection are not assigned to the `Arguments` property. [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] -## Examples - The first example creates a small application (argsecho.exe) that echos its arguments to the console. The second example creates an application that invokes argsecho.exe to demonstrate different variations for the `Arguments` property. - +## Examples + The first example creates a small application (argsecho.exe) that echos its arguments to the console. The second example creates an application that invokes argsecho.exe to demonstrate different variations for the `Arguments` property. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic3.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstartstatic3.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic3.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic3.vb"::: + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic2.cpp"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstartstatic2.cs"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic2.vb"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic2.vb"::: + ]]> @@ -530,20 +530,20 @@ If you use this property to set command-line arguments, if the process should be started without creating a new window to contain it; otherwise, . The default is . - property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. + property is `true` or the and properties are not `null`, the property value is ignored and a new window is created. .NET Core does not support creating windows directly on Unix-like platforms, including macOS and Linux. This property is ignored on such platforms. - - - -## Examples + + + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstart.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb" id="Snippet1"::: + ]]> @@ -656,13 +656,13 @@ If you use this property to set command-line arguments, Gets the environment variables that apply to this process and its child processes. A generic dictionary containing the environment variables that apply to this process and its child processes. The default is . - property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. - - On .NET Framework applications, using the property is the same as using the property. - + property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. + + On .NET Framework applications, using the property is the same as using the property. + ]]> @@ -745,11 +745,11 @@ If you use this property to set command-line arguments, Gets search paths for files, directories for temporary files, application-specific options, and other similar information. A string dictionary that provides environment variables that apply to this process and child processes. The default is . - property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. - + property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to `false` to start the process after changing the property. If is `true`, an is thrown when the method is called. + ]]> @@ -818,13 +818,13 @@ If you use this property to set command-line arguments, if an error dialog box should be displayed on the screen if the process cannot be started; otherwise, . The default is . - [!NOTE] -> must be `true` if you want to set to `true`. - +> must be `true` if you want to set to `true`. + ]]> @@ -884,11 +884,11 @@ If you use this property to set command-line arguments, Gets or sets the window handle to use when an error dialog box is shown for a process that cannot be started. A pointer to the handle of the error dialog box that results from a process start failure. - is `true`, the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. - + is `true`, the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. + ]]> @@ -993,22 +993,22 @@ If you use this property to set command-line arguments, Gets or sets the application or document to start. The name of the application to start, or the name of a document of a file type that is associated with an application and that has a default open action available to it. The default is an empty string (""). - property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. - - The set of file types available to you depends in part on the value of the property. If is `true`, you can start any document and perform operations on the file, such as printing, with the component. When is `false`, you can start only executables with the component. - - You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard disk. - - [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] - -## Examples + property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the **Folder Options** dialog box, which is available through the operating system. The **Advanced** button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + + The set of file types available to you depends in part on the value of the property. If is `true`, you can start any document and perform operations on the file, such as printing, with the component. When is `false`, you can start only executables with the component. + + You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard disk. + + [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] + +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/Overview/processstart.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb" id="Snippet1"::: + ]]> @@ -1069,17 +1069,17 @@ If you use this property to set command-line arguments, if the Windows user profile should be loaded; otherwise, . The default is . - @@ -1151,23 +1151,23 @@ If you use this property to set command-line arguments, Gets or sets a secure string that contains the user password to use when starting the process. The user password to use when starting the process. - [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. - +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. + > [!NOTE] -> Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. - - A object is like a object in that it has a text value. However, the value of a object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application or the .NET Framework garbage collector. - - For more information about secure strings and an example of how to obtain a password to set this property, see the class. - +> Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. + + A object is like a object in that it has a text value. However, the value of a object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application or the .NET Framework garbage collector. + + For more information about secure strings and an example of how to obtain a password to set this property, see the class. + > [!NOTE] -> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. - +> If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. + ]]> @@ -1302,48 +1302,48 @@ If you use this property to set command-line arguments, if error output should be written to ; otherwise, . The default is . - writes text to its standard error stream, that text is typically displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. - + writes text to its standard error stream, that text is typically displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + > [!NOTE] -> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. - - The redirected stream can be read synchronously or asynchronously. Methods such as , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. - +> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. + + The redirected stream can be read synchronously or asynchronously. Methods such as , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. - - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. + + Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/write500lines.vb"::: -The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling `p.StandardError.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardError.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. +The following example shows how to read from a redirected error stream and wait for the child process to exit. It avoids a deadlock condition by calling `p.StandardError.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardError.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardError/stderror-sync.cs"::: -:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standarderror/stderror-sync.vb"::: - -There is a similar issue when you read all text from both the standard output and standard error streams. The following C# code, for example, performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. +:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standarderror/stderror-sync.vb"::: + +There is a similar issue when you read all text from both the standard output and standard error streams. The following C# code, for example, performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: -:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: - -You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. - - - -## Examples - The following example uses the `net use` command together with a user-supplied argument to map a network resource. It then reads the standard error stream of the net command and writes it to console. - +:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: + +You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. + + + +## Examples + The following example uses the `net use` command together with a user-supplied argument to map a network resource. It then reads the standard error stream of the net command and writes it to console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process_StandardError/CPP/source.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardError/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process_StandardError/VB/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process_StandardError/VB/source.vb" id="Snippet1"::: + ]]> @@ -1415,25 +1415,25 @@ You can use asynchronous read operations to avoid these dependencies and their d if input should be read from ; otherwise, . The default is . - can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input of a process. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. - + can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input of a process. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. + > [!NOTE] -> You must set to `false` if you want to set to `true`. Otherwise, writing to the stream throws an exception. - - - -## Examples - The following example illustrates how to redirect the stream of a process. The `sort` command is a console application that reads and sorts text input. - - The example starts the `sort` command with redirected input. It then prompts the user for text, and passes the text to the `sort` process through the redirected stream. The `sort` results are displayed to the user on the console. - +> You must set to `false` if you want to set to `true`. Otherwise, writing to the stream throws an exception. + + + +## Examples + The following example illustrates how to redirect the stream of a process. The `sort` command is a console application that reads and sorts text input. + + The example starts the `sort` command with redirected input. It then prompts the user for text, and passes the text to the `sort` process through the redirected stream. The `sort` results are displayed to the user on the console. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/Process_StandardInput/CPP/process_standardinput.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardInput/process_standardinput.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process_StandardInput/VB/process_standardinput.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/Process_StandardInput/VB/process_standardinput.vb" id="Snippet1"::: + ]]> @@ -1505,46 +1505,46 @@ You can use asynchronous read operations to avoid these dependencies and their d if output should be written to ; otherwise, . The default is . - writes text to its standard stream, that text is typically displayed on the console. By setting to `true` to redirect the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. - + writes text to its standard stream, that text is typically displayed on the console. By setting to `true` to redirect the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + > [!NOTE] -> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. - - The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. - - In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler (see ) for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. - +> You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. + + The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + + In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler (see ) for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + > [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. - - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. - +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. + + Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. + The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/write500lines.cs"::: :::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/write500lines.vb"::: -The following example shows how to read from a redirected stream and wait for the child process to exit. The example avoids a deadlock condition by calling `p.StandardOutput.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardOutput.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. +The following example shows how to read from a redirected stream and wait for the child process to exit. The example avoids a deadlock condition by calling `p.StandardOutput.ReadToEnd` before `p.WaitForExit`. A deadlock condition can result if the parent process calls `p.WaitForExit` before `p.StandardOutput.ReadToEnd` and the child process writes enough text to fill the redirected stream. The parent process would wait indefinitely for the child process to exit. The child process would wait indefinitely for the parent to read from the full stream. + +:::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.cs"::: +:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-sync.vb"::: + +There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. +:::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: +:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: + +You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. -:::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-sync.cs"::: -:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-sync.vb"::: -There is a similar issue when you read all text from both the standard output and standard error streams. The following example performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. -:::code language="csharp" source="~/snippets/csharp/System.Diagnostics/Process/StandardOutput/stdoutput-async.cs"::: -:::code language="vb" source="~/snippets/visualbasic/api/system.diagnostics/process/standardoutput/stdoutput-async.vb"::: -You can use asynchronous read operations to avoid these dependencies and their deadlock potential. Alternately, you can avoid the deadlock condition by creating two threads and reading the output of each stream on a separate thread. - - - -## Examples +## Examples :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR/ProcessOneStream/CPP/stdstr.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessStartInfo/RedirectStandardOutput/stdstr.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ProcessOneStream/VB/stdstr.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ProcessOneStream/VB/stdstr.vb" id="Snippet1"::: + ]]> @@ -1611,11 +1611,11 @@ You can use asynchronous read operations to avoid these dependencies and their d Gets or sets the preferred encoding for error output. An object that represents the preferred encoding for error output. The default is . - property is `null`, the process uses the default standard error encoding for error output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding; the process will use only those encodings that it supports. The application should be tested to determine which encodings are supported. - + property is `null`, the process uses the default standard error encoding for error output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding; the process will use only those encodings that it supports. The application should be tested to determine which encodings are supported. + ]]> @@ -1663,11 +1663,11 @@ You can use asynchronous read operations to avoid these dependencies and their d Gets or sets the preferred encoding for standard input. An object that represents the preferred encoding for standard input. The default is . - @@ -1732,11 +1732,11 @@ You can use asynchronous read operations to avoid these dependencies and their d Gets or sets the preferred encoding for standard output. An object that represents the preferred encoding for standard output. The default is . - property is `null`, the process uses the default standard output encoding for the standard output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding. The application should be tested to determine which encodings the process supports. - + property is `null`, the process uses the default standard output encoding for the standard output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding. The application should be tested to determine which encodings the process supports. + ]]> @@ -1818,15 +1818,15 @@ You can use asynchronous read operations to avoid these dependencies and their d Gets or sets the user name to use when starting the process. If you use the UPN format, @, the property must be . The user name to use when starting the process. If you use the UPN format, @, the property must be . - [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. - - If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. - +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. + + If the property is not `null` or an empty string, the property must be `false`, or an will be thrown when the method is called. + ]]> @@ -1910,8 +1910,6 @@ When you use the operating system shell to start processes, you can start any do > [!NOTE] > must be `true` if you set the property to `true`. -If you set the to , must be set to `true`. - ### WorkingDirectory The property behaves differently depending on the value of the property. When is `true`, the property specifies the location of the executable. If is an empty string, it is assumed that the current directory contains the executable. @@ -2011,21 +2009,21 @@ When is `false`, the Gets or sets the verb to use when opening the application or document specified by the property. The action to take with the file that the process opens. The default is an empty string (""), which signifies no action. - property. For example, the "`print`" verb will print a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. - - When you use the property, you must include the file name extension when you set the value of the property. The file name does not need to have an extension if you manually enter a value for the property. - - - -## Examples - The following code example starts a new process by using the specified verb and file name. This code example is part of a larger example provided for the property. - + property. For example, the "`print`" verb will print a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. + + When you use the property, you must include the file name extension when you set the value of the property. The file name does not need to have an extension if you manually enter a value for the property. + + + +## Examples + The following code example starts a new process by using the specified verb and file name. This code example is part of a larger example provided for the property. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessStartInfo/Verb/source.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ProcessVerbs_Diagnostics/VB/source.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ProcessVerbs_Diagnostics/VB/source.vb" id="Snippet4"::: + ]]> @@ -2078,23 +2076,23 @@ When is `false`, the Gets the set of verbs associated with the type of file specified by the property. The actions that the system can apply to the file indicated by the property. - property enables you to determine the verbs that can be used with the file specified by the property. You can set the property to the value of any verb in the set. Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". - + property enables you to determine the verbs that can be used with the file specified by the property. You can set the property to the value of any verb in the set. Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". + Be aware that the resulting list of verbs may not contain all possible values, e.g. "New" is by design not added to the list and other possible verbs are not always detected depending on your system setup. - - When you use the property, you must include the file name extension when you set the value of the property. The file name extension determines the set of possible verbs. - - - -## Examples - The following code example displays the defined verbs for the chosen file name. If the user selects one of the defined verbs, the example starts a new process using the selected verb and the input file name. - + + When you use the property, you must include the file name extension when you set the value of the property. The file name extension determines the set of possible verbs. + + + +## Examples + The following code example displays the defined verbs for the chosen file name. If the user selects one of the defined verbs, the example starts a new process using the selected verb and the input file name. + :::code language="csharp" source="~/snippets/csharp/System.Diagnostics/ProcessStartInfo/Verb/source.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ProcessVerbs_Diagnostics/VB/source.vb" id="Snippet3"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR/ProcessVerbs_Diagnostics/VB/source.vb" id="Snippet3"::: + ]]> @@ -2163,13 +2161,13 @@ When is `false`, the Gets or sets the window state to use when the process is started. One of the enumeration values that indicates whether the process is started in a window that is maximized, minimized, normal (neither maximized nor minimized), or not visible. The default is . - The window style is not one of the enumeration members. @@ -2275,22 +2273,22 @@ When is `false`, the When the property is , gets or sets the working directory for the process to be started. When is , gets or sets the directory that contains the process to be started. When is , the fully qualified name of the directory that contains the process to be started. When the property is , the working directory for the process to be started. The default is an empty string (""). - [!IMPORTANT] -> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. - - If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property. - - The property behaves differently when is `true` than when is `false`. When is `true`, the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. - +> The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. + + If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property. + + The property behaves differently when is `true` than when is `false`. When is `true`, the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. + > [!NOTE] -> When is `true`, the working directory of the application that starts the executable is also the working directory of the executable. - - When is `false`, the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. - +> When is `true`, the working directory of the application that starts the executable is also the working directory of the executable. + + When is `false`, the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. + ]]> diff --git a/xml/System.Linq/Enumerable.xml b/xml/System.Linq/Enumerable.xml index d5df1e0d3ed..a7a08e6fe93 100644 --- a/xml/System.Linq/Enumerable.xml +++ b/xml/System.Linq/Enumerable.xml @@ -12818,6 +12818,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl is . + The sum is larger than Double.MaxValue. Aggregate Clause (Visual Basic) @@ -13049,6 +13050,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl is . + The sum is larger than Double.MaxValue. Aggregate Clause (Visual Basic) @@ -13228,6 +13230,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl is . + The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) @@ -13291,6 +13294,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl is . + The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) @@ -13450,6 +13454,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl or is . + The sum is larger than Double.MaxValue. Aggregate Clause (Visual Basic) @@ -13773,6 +13778,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl or is . + The sum is larger than Double.MaxValue. Aggregate Clause (Visual Basic) @@ -14015,6 +14021,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl or is . + The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) @@ -14095,6 +14102,7 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl or is . + The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) From 316723acae74b94621af9adaa25c9ba2033c9099 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 9 Nov 2023 11:29:43 -0800 Subject: [PATCH 2/2] Float overloads don't throw OverflowException --- xml/System.Linq/Enumerable.xml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/xml/System.Linq/Enumerable.xml b/xml/System.Linq/Enumerable.xml index a7a08e6fe93..d0fcddbbc38 100644 --- a/xml/System.Linq/Enumerable.xml +++ b/xml/System.Linq/Enumerable.xml @@ -13230,7 +13230,6 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl is . - The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) @@ -13294,7 +13293,6 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl is . - The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) @@ -14021,7 +14019,6 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl or is . - The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic) @@ -14102,7 +14099,6 @@ In Visual Basic query expression syntax, an `Aggregate Into Sum()` clause transl or is . - The sum is larger than Single.MaxValue. Aggregate Clause (Visual Basic)