diff --git a/xml/System.Diagnostics/ProcessStartInfo.xml b/xml/System.Diagnostics/ProcessStartInfo.xml index 1c22b515716..e0214dc86fe 100644 --- a/xml/System.Diagnostics/ProcessStartInfo.xml +++ b/xml/System.Diagnostics/ProcessStartInfo.xml @@ -71,9 +71,7 @@ [!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). - - +> 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. @@ -309,34 +307,25 @@ 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 . +`ArgumentList` and the property are independent of one another and **only one of them can be used at the same time**. The main difference between these APIs is that `ArgumentList` escapes the provided arguments and **internally** builds a single string that's passed to the operating system when calling `Process.Start(info)`. So if you aren't sure how to properly escape your arguments, you should choose `ArgumentList` over . [!INCLUDE [untrusted-data-instance-note](~/includes/untrusted-data-instance-note.md)] -``` ## Examples This example adds three arguments to the process start info. ```csharp -var info = new System.Diagnostics.ProcessStartInfo("cmd.exe"); -info.ArgumentList.Add("/c"); -info.ArgumentList.Add("dir"); -info.ArgumentList.Add(@"C:\Program Files\dotnet"); // there is no need to escape the space, the API takes care of it - -// or if you prefer collection property initializer syntax: - var info = new System.Diagnostics.ProcessStartInfo("cmd.exe") { ArgumentList = { "/c", "dir", - @"C:\Program Files\dotnet" + @"C:\Program Files\dotnet" // The space character is escaped automatically. } }; // The corresponding assignment to the Arguments property is: - var info = new System.Diagnostics.ProcessStartInfo("cmd.exe") { Arguments = "/c dir \"C:\\Program Files\\dotnet\"" @@ -349,7 +338,6 @@ info.ArgumentList.Add("dir") info.ArgumentList.Add("C:\Program Files\dotnet") ' The corresponding assignment to the Arguments property is: - info.Arguments = "/c dir ""C:\Program Files\dotnet""" ``` ]]> @@ -807,7 +795,7 @@ If you use this property to set command-line arguments, [!NOTE] -> must be `true` if you want to set to `true`. +> must be `true` if you want to set to `true`. ]]> @@ -1124,17 +1112,17 @@ If you use this property to set command-line arguments, [!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. +> 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. ]]> @@ -1266,14 +1254,14 @@ If you use this property to set command-line arguments, 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. +> 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. +> 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. @@ -1376,7 +1364,7 @@ You can use asynchronous read operations to avoid these dependencies and their d A 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. +> You must set to `false` if you want to set to `true`. Otherwise, writing to the stream throws an exception. @@ -1463,14 +1451,14 @@ You can use asynchronous read operations to avoid these dependencies and their d When a 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. +> 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. +> 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. @@ -1490,8 +1478,6 @@ There is a similar issue when you read all text from both the standard output an 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 :::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"::: @@ -1756,7 +1742,7 @@ You can use asynchronous read operations to avoid these dependencies and their d ## Remarks > [!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. 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. @@ -1920,7 +1906,8 @@ Each file name extension has its own set of verbs, which can be obtained by usin 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. + +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"::: @@ -2164,14 +2151,14 @@ When you use the property, yo ## Remarks > [!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. 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 `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.