diff --git a/includes/remarks/System.Diagnostics/DataReceivedEventArgs/Data.md b/includes/remarks/System.Diagnostics/DataReceivedEventArgs/Data.md new file mode 100644 index 00000000000..6c923c309af --- /dev/null +++ b/includes/remarks/System.Diagnostics/DataReceivedEventArgs/Data.md @@ -0,0 +1,14 @@ +When you redirect the or stream of a to your event handler, an event is raised each time the process writes a line to the redirected stream. The property is the line that the wrote to the redirected output stream. Your event handler can use the property to filter process output or write output to an alternate location. For example, you might create an event handler that stores all error output lines into a designated error log file. + +A line is defined as a sequence of characters followed by a line feed ("\n") or a carriage return immediately followed by a line feed ("\r\n"). The line characters are encoded using the default system ANSI code page. The property does not include the terminating carriage return or line feed. + +When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. + +## Examples + +The following code example illustrates a simple event handler associated with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + +[!code-cpp[Process_AsyncStreams#4](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/datareceivedevent.cpp#4)] +[!code-csharp[Process_AsyncStreams#4](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/datareceivedevent.cs#4)] +[!code-vb[Process_AsyncStreams#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/datareceivedevent.vb#4)] + diff --git a/includes/remarks/System.Diagnostics/DataReceivedEventArgs/DataReceivedEventArgs.md b/includes/remarks/System.Diagnostics/DataReceivedEventArgs/DataReceivedEventArgs.md new file mode 100644 index 00000000000..0b741e2815c --- /dev/null +++ b/includes/remarks/System.Diagnostics/DataReceivedEventArgs/DataReceivedEventArgs.md @@ -0,0 +1,12 @@ +To asynchronously collect the redirected or stream output of a process, you must create a method that handles the redirected stream output events. The event-handler method is called when the process writes to the redirected stream. The event delegate calls your event handler with an instance of . The property contains the text line that the process wrote to the redirected stream. + +## Examples + +The following code example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. + +The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + +[!code-cpp[Process_AsyncStreams#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/sort_async.cpp#1)] +[!code-csharp[Process_AsyncStreams#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/sort_async.cs#1)] +[!code-vb[Process_AsyncStreams#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/sort_async.vb#1)] + diff --git a/includes/remarks/System.Diagnostics/DataReceivedEventHandler/DataReceivedEventHandler.md b/includes/remarks/System.Diagnostics/DataReceivedEventHandler/DataReceivedEventHandler.md new file mode 100644 index 00000000000..5a44ef0cfcd --- /dev/null +++ b/includes/remarks/System.Diagnostics/DataReceivedEventHandler/DataReceivedEventHandler.md @@ -0,0 +1,13 @@ +When you create a delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). + +To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. + +## Examples + +The following code example illustrates how to perform asynchronous read operations on the redirected stream of the **sort** command. The **sort** command is a console application that reads and sorts text input. + +The example creates a delegate for the `SortOutputHandler` event handler and associates the delegate with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + +[!code-cpp[Process_AsyncStreams#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/sort_async.cpp#1)] +[!code-csharp[Process_AsyncStreams#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/sort_async.cs#1)] +[!code-vb[Process_AsyncStreams#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/sort_async.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/.ctor.md b/includes/remarks/System.Diagnostics/Process/.ctor.md new file mode 100644 index 00000000000..04a88017a34 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/.ctor.md @@ -0,0 +1,11 @@ +If you do not specify the property, the default is the local computer, ("."). + +You have two options for associating a new component with a process on the computer. The first option is to use the constructor to create the component, set the appropriate members of the property and call to associate the with a new system process. The second option is to associate the with a running system process by using or one of the return values. + +If you use a `static` overload of the method to start a new system process, the method creates a new component and associates it with the process. + +When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. + +Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. + +You can create a component by using the constructor, one of the static overloads, or any of the , , or methods. After you have done so, you have a view into the associated process. This is not a dynamic view that updates itself automatically when the process properties have changed in memory. Instead, you must call for the component to update the property information in your application. diff --git a/includes/remarks/System.Diagnostics/Process/BasePriority.md b/includes/remarks/System.Diagnostics/Process/BasePriority.md new file mode 100644 index 00000000000..80be857898d --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/BasePriority.md @@ -0,0 +1,23 @@ +The value returned by this property represents the most recently refreshed base priority of the process. To get the most up to date base priority, you need to call method first. + +The of the process is the starting priority for threads created within the associated process. You can view information about the base priority through the System Monitor's Priority Base counter. + +Based on the time elapsed or other boosts, the operating system can change the base priority when a process should be placed ahead of others. + +The property lets you view the starting priority assigned to a process. However, because it is read-only, you cannot use the to set the priority of the process. To change the priority, use the property. The is viewable using the System Monitor, while the is not. Both the and the can be viewed programmatically. The following table shows the relationship between values and values. + +|BasePriority|PriorityClass| +|------------------|-------------------| +|4|| +|8|| +|13|| +|24|| + + +## Examples + +The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. + +[!code-cpp[Diag_Process_MemoryProperties64#1](~/samples/snippets/cpp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CPP/source.cpp#1)] +[!code-csharp[Diag_Process_MemoryProperties64#1](~/samples/snippets/csharp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CS/source.cs#1)] +[!code-vb[Diag_Process_MemoryProperties64#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Diag_Process_MemoryProperties64/VB/source.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/BeginErrorReadLine.md b/includes/remarks/System.Diagnostics/Process/BeginErrorReadLine.md new file mode 100644 index 00000000000..b72d979eec0 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/BeginErrorReadLine.md @@ -0,0 +1,31 @@ +The 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 the 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. + +Follow these steps to perform asynchronous read operations on for a : + +1. Set to `false`. + +2. Set to `true`. + +3. Add your event handler to the event. The event handler must match the delegate signature. + +4. Start the . + +5. Call for the . This call starts asynchronous read operations on . + +When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. + +You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. + +> [!NOTE] +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. + + +## Examples + +The following example uses the `net view` command to list the available network resources on a remote computer. The user supplies the target computer name as a command-line argument. The user can also supply a file name for error output. The example collects the output of the net command, waits for the process to finish, and then writes the output results to the console. If the user supplies the optional error file, the example writes errors to the file. + +[!code-cpp[Process_AsyncStreams#2](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/net_async.cpp#2)] +[!code-csharp[Process_AsyncStreams#2](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/net_async.cs#2)] +[!code-vb[Process_AsyncStreams#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/net_async.vb#2)] diff --git a/includes/remarks/System.Diagnostics/Process/BeginOutputReadLine.md b/includes/remarks/System.Diagnostics/Process/BeginOutputReadLine.md new file mode 100644 index 00000000000..d37b114c20f --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/BeginOutputReadLine.md @@ -0,0 +1,33 @@ +The 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 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. + +Follow these steps to perform asynchronous read operations on for a : + +1. Set to `false`. + +2. Set to `true`. + +3. Add your event handler to the event. The event handler must match the delegate signature. + +4. Start the . + +5. Call for the . This call starts asynchronous read operations on . + +When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. + +You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. + +> [!NOTE] +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. + +## Examples + +The following example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. + +The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. + +[!code-cpp[Process_AsyncStreams#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/sort_async.cpp#1)] +[!code-csharp[Process_AsyncStreams#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/sort_async.cs#1)] +[!code-vb[Process_AsyncStreams#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/sort_async.vb#1)] + diff --git a/includes/remarks/System.Diagnostics/Process/CancelErrorRead.md b/includes/remarks/System.Diagnostics/Process/CancelErrorRead.md new file mode 100644 index 00000000000..a0296f07bc7 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/CancelErrorRead.md @@ -0,0 +1,30 @@ + starts an asynchronous read operation on the stream. ends the asynchronous read operation. + +After canceling, you can resume the asynchronous read operation by calling again. + +When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to will be lost. If you re-enable the event handler with a call to , asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: + +```csharp +// At this point the DataReceivedEventHandler(ErrorHandler1) +// has executed a CancelErrorRead. + +// Remove the prior event handler. +process.ErrorDataReceived -= new DataReceivedEventHandler(ErrorHandler1); + +// Register a new event handler. +process.ErrorDataReceived += new DataReceivedEventHandler(ErrorHandler2); + +// Call the corresponding BeginErrorReadLine. +process.BeginErrorReadLine(); +``` + +> [!NOTE] +> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . + +## Examples + +The following example starts the `nmake` command with user supplied arguments. The error and output streams are read asynchronously; the collected text lines are displayed to the console as well as written to a log file. If the command output exceeds a specified number of lines, the asynchronous read operations are canceled. + +[!code-cpp[Process_AsyncStreams#3](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/nmake_async.cpp#3)] +[!code-csharp[Process_AsyncStreams#3](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/nmake_async.cs#3)] +[!code-vb[Process_AsyncStreams#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/nmake_async.vb#3)] diff --git a/includes/remarks/System.Diagnostics/Process/CancelOutputRead.md b/includes/remarks/System.Diagnostics/Process/CancelOutputRead.md new file mode 100644 index 00000000000..8e643e36644 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/CancelOutputRead.md @@ -0,0 +1,31 @@ + starts an asynchronous read operation on the stream. ends the asynchronous read operation. + +After canceling, you can resume asynchronous read operations by calling again. + +When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to is saved in a buffer. If you re-enable the event handler with a call to , the saved output is sent to the event handler and asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: + +```csharp +// At this point the DataReceivedEventHandler(OutputHandler1) +// has executed a CancelOutputRead. + +// Remove the prior event handler. +process.OutputDataReceived -= new DataReceivedEventHandler(OutputHandler1); + +// Register a new event handler. +process.OutputDataReceived += new DataReceivedEventHandler(OutputHandler2); + +// Call the corresponding BeginOutputReadLine. +process.BeginOutputReadLine(); +``` + +> [!NOTE] +> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . + + +## Examples + +The following example starts the `nmake` command with user supplied arguments. The error and output streams are read asynchronously; the collected text lines are displayed to the console as well as written to a log file. If the command output exceeds a specified number of lines, the asynchronous read operations are canceled. + +[!code-cpp[Process_AsyncStreams#3](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/nmake_async.cpp#3)] +[!code-csharp[Process_AsyncStreams#3](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/nmake_async.cs#3)] +[!code-vb[Process_AsyncStreams#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/nmake_async.vb#3)] \ No newline at end of file diff --git a/includes/remarks/System.Diagnostics/Process/EnableRaisingEvents.md b/includes/remarks/System.Diagnostics/Process/EnableRaisingEvents.md new file mode 100644 index 00000000000..4b0b03fb377 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/EnableRaisingEvents.md @@ -0,0 +1,19 @@ +The property suggests whether the component should be notified when the operating system has shut down a process. The property is used in asynchronous processing to notify your application that a process has exited. To force your application to synchronously wait for an exit event (which interrupts processing of the application until the exit event has occurred), use the method. + +> [!NOTE] +> If you're using Visual Studio and double-click a component in your project, an event delegate and event handler are automatically generated. Additional code sets the property to `false`. You must change this property to `true` for your event handler to execute when the associated process exits. + +If the component's value is `true`, or when is `false` and a check is invoked by the component, the component can access the administrative information for the associated process. This information remains stored by the operating system and includes the and the . + +After the associated process exits, the of the component no longer points to an existing process resource. Instead, it can only be used to access the operating system's information about the process resource. The operating system is aware that there are handles to exited processes that haven't been released by components, so it keeps the and information in memory. + +There's a cost associated with watching for a process to exit. If is `true`, the event is raised when the associated process terminates. Your procedures for the event run at that time. + +Sometimes, your application starts a process but doesn't require notification of its closure. For example, your application can start Notepad to allow the user to perform text editing but make no further use of the Notepad application. You can choose to avoid notification when the process exits because it's not relevant to the continued operation of your application. Setting to `false` can save system resources. + +## Examples + +The following code example creates a process that prints a file. It sets the property to cause the process to raise the event when it exits. The event handler displays process information. + +[!code-csharp[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/CS/processexitedevent.cs#1)] +[!code-vb[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/VB/processexitedevent.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/ErrorDataReceived.md b/includes/remarks/System.Diagnostics/Process/ErrorDataReceived.md new file mode 100644 index 00000000000..0560ed6d4cf --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/ErrorDataReceived.md @@ -0,0 +1,15 @@ +The event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. + +The event only occurs during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . + +> [!NOTE] +> The application that's processing the asynchronous output should call the method to ensure that the output buffer has been flushed. +Specifying a timeout by using the overload does *not* ensure the output buffer has been flushed. + +## Examples + +The following example uses the `net view` command to list the available network resources on a remote computer. The user supplies the target computer name as a command-line argument. The user can also supply a file name for error output. The example collects the output of the net command, waits for the process to finish, and then writes the output results to the console. If the user supplies the optional error file, the example writes errors to the file. + +[!code-cpp[Process_AsyncStreams#2](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/net_async.cpp#2)] +[!code-csharp[Process_AsyncStreams#2](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/net_async.cs#2)] +[!code-vb[Process_AsyncStreams#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/net_async.vb#2)] diff --git a/includes/remarks/System.Diagnostics/Process/ExitCode.md b/includes/remarks/System.Diagnostics/Process/ExitCode.md new file mode 100644 index 00000000000..6a305fddf6b --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/ExitCode.md @@ -0,0 +1,22 @@ +Use to get the status that the system process returned when it exited. You can use the exit code much like an integer return value from a `main()` procedure. + +The value for a process reflects the specific convention implemented by the application developer for that process. If you use the exit code value to make decisions in your code, be sure that you know the exit code convention used by the application process. + +Developers usually indicate a successful exit by an value of zero, and designate errors by nonzero values that the calling method can use to identify the cause of an abnormal process termination. It is not necessary to follow these guidelines, but they are the convention. + +If you try to get the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. + +> [!NOTE] +> When standard output has been redirected to asynchronous event handlers, it's possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no arguments before checking . + +You can use the or the method to cause an associated process to exit. + +There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification relies on calling the method to pause the processing of your application until the associated component exits. Asynchronous notification relies on the event. When using asynchronous notification, must be set to `true` for the component to receive notification that the process has exited. + +## Examples + +The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. + +[!code-cpp[Diag_Process_MemoryProperties64#1](~/samples/snippets/cpp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CPP/source.cpp#1)] +[!code-csharp[Diag_Process_MemoryProperties64#1](~/samples/snippets/csharp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CS/source.cs#1)] +[!code-vb[Diag_Process_MemoryProperties64#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Diag_Process_MemoryProperties64/VB/source.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/Exited.md b/includes/remarks/System.Diagnostics/Process/Exited.md new file mode 100644 index 00000000000..5592f2ba34e --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Exited.md @@ -0,0 +1,17 @@ +The event indicates that the associated process exited. This occurrence means either that the process terminated (aborted) or successfully closed. This event can occur only if the value of the property is `true`. + +There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification means calling the method to block the current thread until the process exits. Asynchronous notification uses the event, which allows the calling thread to continue execution in the meantime. In the latter case, must be set to `true` for the calling application to receive the Exited event. + +When the operating system shuts down a process, it notifies all other processes that have registered handlers for the Exited event. At this time, the handle of the process that just exited can be used to access some properties such as and that the operating system maintains until it releases that handle completely. + +> [!NOTE] +> Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . + +For more information about the use of the event in Windows Forms applications, see the property. + +## Examples + +The following code example creates a process that prints a file. It raises the event when the process exits because the property was set when the process was created. The event handler displays process information. + +[!code-csharp[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/CS/processexitedevent.cs#1)] +[!code-vb[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/VB/processexitedevent.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/GetProcessById_Int32.md b/includes/remarks/System.Diagnostics/Process/GetProcessById_Int32.md new file mode 100644 index 00000000000..23503fd68f7 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/GetProcessById_Int32.md @@ -0,0 +1,13 @@ +Use this method to create a new component and associate it with a process resource on the local computer. The process resource must already exist on the computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. + +On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. + +The `processId` parameter is an (a 32-bit signed integer), although the underlying Windows API uses a `DWORD` (an unsigned 32-bit integer) for similar APIs. This is for historical reasons. + +## Examples + +The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. + +[!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] +[!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] +[!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/GetProcessById_Int32_String.md b/includes/remarks/System.Diagnostics/Process/GetProcessById_Int32_String.md new file mode 100644 index 00000000000..97bb1d74842 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/GetProcessById_Int32_String.md @@ -0,0 +1,15 @@ +Use this method to create a new component and associate it with a process resource on a remote computer on the network. The process resource must already exist on the specified computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. + +On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. + +If you do not specify a `machineName`, the local computer is used. Alternatively, you can specify the local computer by setting `machineName` to the value "." or to an empty string (""). + +The `processId` parameter is an (a 32-bit signed integer), although the underlying Windows API uses a `DWORD` (an unsigned 32-bit integer) for similar APIs. This is for historical reasons. + +## Examples + +The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. + +[!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] +[!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] +[!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/GetProcesses.md b/includes/remarks/System.Diagnostics/Process/GetProcesses.md new file mode 100644 index 00000000000..f0c4efd275c --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/GetProcesses.md @@ -0,0 +1,14 @@ +Use this method to create an array of new components and associate them with all the process resources on the local computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. + +If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. + +> [!NOTE] +> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . + +## Examples + +The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. + +[!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] +[!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] +[!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/GetProcessesByName_String.md b/includes/remarks/System.Diagnostics/Process/GetProcessesByName_String.md new file mode 100644 index 00000000000..1e47786f067 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/GetProcessesByName_String.md @@ -0,0 +1,14 @@ +Use this method to create an array of new components and associate them with all the process resources that are running the same executable file on the local computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. + +The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. + +Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. + +## Examples + +The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. + +[!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] +[!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] +[!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] + diff --git a/includes/remarks/System.Diagnostics/Process/GetProcessesByName_String_String.md b/includes/remarks/System.Diagnostics/Process/GetProcessesByName_String_String.md new file mode 100644 index 00000000000..11f2a93eed4 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/GetProcessesByName_String_String.md @@ -0,0 +1,18 @@ +Use this method to create an array of new components and associate them with all the process resources that are running the same executable file on the specified computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. + +The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. + +Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. + +You can use this overload to get processes on the local computer as well as on a remote computer. Use "." to specify the local computer. Another overload exists that uses the local computer by default. + +You can access processes on remote computers only to view information, such as statistics, about the processes. You cannot close, terminate (using ), or start processes on remote computers. + +## Examples + +The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. + +[!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] +[!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] +[!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] + diff --git a/includes/remarks/System.Diagnostics/Process/GetProcesses_String.md b/includes/remarks/System.Diagnostics/Process/GetProcesses_String.md new file mode 100644 index 00000000000..c7c6a335aef --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/GetProcesses_String.md @@ -0,0 +1,16 @@ +Use this method to create an array of new components and associate them with all the process resources on the specified (usually remote) computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. + +If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. + +This overload of the method is generally used to retrieve the list of process resources running on a remote computer on the network, but you can specify the local computer by passing ".". + +> [!NOTE] +> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . + +## Examples + +The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. + +[!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] +[!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] +[!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/HasExited.md b/includes/remarks/System.Diagnostics/Process/HasExited.md new file mode 100644 index 00000000000..97a2261d5c6 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/HasExited.md @@ -0,0 +1,14 @@ +A value of `true` for indicates that the associated process has terminated, either normally or abnormally. You can request or force the associated process to exit by calling or . If a handle is open to the process, the operating system releases the process memory when the process has exited, but retains administrative information about the process, such as the handle, exit code, and exit time. To get this information, you can use the and properties. These properties are populated automatically for processes that were started by this component. The administrative information is released when all the components that are associated with the system process are destroyed and hold no more handles to the exited process. + +A process can terminate independently of your code. If you started the process using this component, the system updates the value of automatically, even if the associated process exits independently. + +> [!NOTE] +> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this property returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . + +## Examples + +The following example starts an instance of Notepad. It then retrieves the physical memory usage of the associated process at 2 second intervals for a maximum of 10 seconds. The example detects whether the process exits before 10 seconds have elapsed. The example closes the process if it is still running after 10 seconds. + +[!code-cpp[process_refresh#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_refresh/CPP/process_refresh.cpp#1)] +[!code-csharp[process_refresh#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_refresh/CS/process_refresh.cs#1)] +[!code-vb[process_refresh#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_refresh/VB/process_refresh.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/Id.md b/includes/remarks/System.Diagnostics/Process/Id.md new file mode 100644 index 00000000000..55b945f2286 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Id.md @@ -0,0 +1,14 @@ +The process is not valid if the associated process is not running. Therefore, you should ensure that the process is running before attempting to retrieve the property. Until the process terminates, the process identifier uniquely identifies the process throughout the system. + +You can connect a process that is running on a local or remote computer to a new instance by passing the process identifier to the method. is a `static` method that creates a new component and sets the property for the new instance automatically. + +Process identifiers can be reused by the system. The property value is unique only while the associated process is running. After the process has terminated, the system can reuse the property value for an unrelated process. + +Because the identifier is unique on the system, you can pass it to other threads as an alternative to passing a instance. This action can save system resources yet guarantee that the process is correctly identified. + +## Examples + +The following example demonstrates how to obtain the for all running instances of an application. The code creates a new instance of Notepad, lists all the instances of Notepad, and then allows the user to enter the number to remove a specific instance. + +[!code-csharp[System.Diagnostics.Process.Id#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.Id/CS/program.cs#1)] +[!code-vb[System.Diagnostics.Process.Id#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.Id/VB/program.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/Kill.md b/includes/remarks/System.Diagnostics/Process/Kill.md new file mode 100644 index 00000000000..f9332abd1ba --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Kill.md @@ -0,0 +1,27 @@ +The `Kill` method forces a termination of the process, while only requests a termination. +When a process with a graphical interface is executing, its message loop is in a wait state. +The message loop executes every time a Windows message is sent to the process by the operating system. +Calling sends a request to close the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application. +The request to exit the process by calling does not force the application to quit. +The application can ask for user verification before quitting, or it can refuse to quit. +To force the application to quit, use the `Kill` method. + +The behavior of is identical to that of a user closing an application's main window using the system menu. +Therefore, the request to exit the process by closing the main window does not force the application to quit immediately. + +> [!NOTE] +> The method executes asynchronously. +> After calling the `Kill` method, call the method to wait for the process to exit, or check the property to determine if the process has exited. + +> [!NOTE] +> The method and the property do not reflect the status of descendant processes. +> When `Kill(entireProcessTree: true)` is used, and will indicate that exiting has completed after the given process exits, even if all descendants have not yet exited. + +Data edited by the process or resources allocated to the process can be lost if you call `Kill`. +`Kill` causes an abnormal process termination and should be used only when necessary. + enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. +If fails, you can use `Kill` to terminate the process. +`Kill` is the only way to terminate processes that do not have graphical interfaces. + +You can call `Kill` and only for processes that are running on the local computer. +You cannot cause processes on remote computers to exit. You can only view information for processes running on remote computers. diff --git a/includes/remarks/System.Diagnostics/Process/OutputDataReceived.md b/includes/remarks/System.Diagnostics/Process/OutputDataReceived.md new file mode 100644 index 00000000000..887c366a75e --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/OutputDataReceived.md @@ -0,0 +1,15 @@ +The event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. + +The event is enabled during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . + +> [!NOTE] +> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. + +## Examples +The following example illustrates how to perform asynchronous read operations on the redirected stream of the `ipconfig` command. + +The example creates an event delegate for the `OutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and saves it in an output string that's later shown in the example's console window. + +[!code-cpp[Process_AsyncStreams#4](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/datareceivedevent.cpp#4)] +[!code-csharp[Process_AsyncStreams#4](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/datareceivedevent.cs#4)] +[!code-vb[Process_AsyncStreams#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/datareceivedevent.vb#4)] diff --git a/includes/remarks/System.Diagnostics/Process/PriorityClass.md b/includes/remarks/System.Diagnostics/Process/PriorityClass.md new file mode 100644 index 00000000000..134a3f3f826 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/PriorityClass.md @@ -0,0 +1,22 @@ +The value returned by this property represents the most recently refreshed priority of the process. To get the most up to date priority, you need to call method first. + +A process priority class encompasses a range of thread priority levels. Threads with different priorities that are running in the process run relative to the priority class of the process. Win32 uses four priority classes with seven base priority levels per class. These process priority classes are captured in the enumeration, which lets you set the process priority to , , , , , or . Based on the time elapsed or other boosts, the base priority level can be changed by the operating system when a process needs to be put ahead of others for access to the processor. In addition, you can set the to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. + +The property lets you view the starting priority that is assigned to a process. However, because it is read-only, you cannot use the property to set the priority of a process. To change the priority, use the property, which gets or sets the overall priority category for the process. + +The priority class cannot be viewed using System Monitor. The following table shows the relationship between the and values. + +|BasePriority|PriorityClass| +|------------------|-------------------| +|4|| +|8|| +|13|| +|24|| + +## Examples + +The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. + +[!code-cpp[Diag_Process_MemoryProperties64#1](~/samples/snippets/cpp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CPP/source.cpp#1)] +[!code-csharp[Diag_Process_MemoryProperties64#1](~/samples/snippets/csharp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CS/source.cs#1)] +[!code-vb[Diag_Process_MemoryProperties64#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Diag_Process_MemoryProperties64/VB/source.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/Process.md b/includes/remarks/System.Diagnostics/Process/Process.md new file mode 100644 index 00000000000..734fc5826af --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Process.md @@ -0,0 +1,52 @@ +A component provides access to a process that is running on a computer. A process, in the simplest terms, is a running app. A thread is the basic unit to which the operating system allocates processor time. A thread can execute any part of the code of the process, including parts currently being executed by another thread. + +The component is a useful tool for starting, stopping, controlling, and monitoring apps. You can use the component, to obtain a list of the processes that are running, or you can start a new process. A component is used to access system processes. After a component has been initialized, it can be used to obtain information about the running process. Such information includes the set of threads, the loaded modules (.dll and .exe files), and performance information such as the amount of memory the process is using. + +This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. + +> [!NOTE] +> 32-bit processes cannot access the modules of a 64-bit process. If you try to get information about a 64-bit process from a 32-bit process, you will get a exception. A 64-bit process, on the other hand, can access the modules of a 32-bit process. + +The process component obtains information about a group of properties all at once. After the component has obtained information about one member of any group, it will cache the values for the other properties in that group and not obtain new information about the other members of the group until you call the method. Therefore, a property value is not guaranteed to be any newer than the last call to the method. The group breakdowns are operating-system dependent. + +If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. + +A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the property of the component, even when the process has exited. Thus, you can get the process's administrative information, such as the (usually either zero for success or a nonzero error code) and the . Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory. + +> [!NOTE] +> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). + + +## .NET Core notes +In .NET Framework, the class by default uses encodings, which are typically code page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, .NET Core may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. + +If a object depends on specific code page encodings, you can still make them available by doing the following *before* you call any methods: + +1. Add a reference to the System.Text.Encoding.CodePages.dll assembly to your project. + +2. Retrieve the object from the property. + +3. Pass the object to the method to make the additional encodings supported by the encoding provider available. + +The class will then automatically use the default system encoding rather than UTF8, provided that you have registered the encoding provider before calling any methods. + + +## Examples + +The following example uses an instance of the class to start a process. + +[!code-cpp[Process.Start_instance#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp#1)] +[!code-csharp[Process.Start_instance#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_instance/CS/processstart.cs#1)] +[!code-vb[Process.Start_instance#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb#1)] + +The following example uses the class itself and a static method to start a process. + +[!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] +[!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] +[!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] + +The following F# example defines a `runProc` function that starts a process, captures all output and error information, and records the number of milliseconds that the process has run. The `runProc` function has three parameters: the name of application to launch, the arguments to supply to the application, and the starting directory. + +[!code-fsharp[System.Diagnostics.Process#1](~/samples/snippets/fsharp/VS_Snippets_CLR_System/system.diagnostics.process/fs/Start1.fs#1)] + +The code for the `runProc` function was written by [ImaginaryDevelopment](http://fssnip.net/authors/ImaginaryDevelopment) and is available under the [Microsoft Public License](https://opensource.org/licenses/ms-pl). diff --git a/includes/remarks/System.Diagnostics/Process/ProcessorAfinity.md b/includes/remarks/System.Diagnostics/Process/ProcessorAfinity.md new file mode 100644 index 00000000000..3edce551cdd --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/ProcessorAfinity.md @@ -0,0 +1,15 @@ +The value returned by this property represents the most recently refreshed affinity of the process. To get the most up to date affinity, you need to call method first. + +In Windows 2000 and later, a thread in a process can migrate from processor to processor, with each migration reloading the processor cache. Under heavy system loads, specifying which processor should run a specific thread can improve performance by reducing the number of times the processor cache is reloaded. The association between a processor and a thread is called the processor affinity. + +Each processor is represented as a bit. Bit 0 is processor one, bit 1 is processor two, and so forth. If you set a bit to the value 1, the corresponding processor is selected for thread assignment. When you set the value to zero, the operating system's scheduling algorithms set the thread's affinity. When the value is set to any nonzero value, the value is interpreted as a bitmask that specifies those processors eligible for selection. + +The following table shows a selection of values for an eight-processor system. + +|Bitmask|Binary value|Eligible processors| +|-------------|------------------|-------------------------| +|0x0001|00000000 00000001|1| +|0x0003|00000000 00000011|1 and 2| +|0x0007|00000000 00000111|1, 2 and 3| +|0x0009|00000000 00001001|1 and 4| +|0x007F|00000000 01111111|1, 2, 3, 4, 5, 6 and 7| diff --git a/includes/remarks/System.Diagnostics/Process/StandardError.md b/includes/remarks/System.Diagnostics/Process/StandardError.md new file mode 100644 index 00000000000..e3562e92746 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/StandardError.md @@ -0,0 +1,38 @@ +When a writes text to its standard error stream, that text is normally 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] +> To use , you must set to `false`, and you must 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. + +Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on 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 on 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 on each other to complete an operation, and neither can proceed. 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-csharp[Executable launched by Process.Start](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/write500lines.cs)] +[!code-vb[Executable launched by Process.Start](~/samples/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. + +[!code-csharp[Reading from the error stream](~/samples/snippets/csharp/api/system.diagnostics/process/standarderror/stderror-sync.cs)] +[!code-vb[Reading from the error stream](~/samples/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 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-csharp[Reading from both streams](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/stdoutput-async.cs)] +[!code-vb[Reading from both streams](~/samples/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. + +> [!NOTE] +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. + +## 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-cpp[Process_StandardError#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process_StandardError/CPP/source.cpp#1)] +[!code-csharp[Process_StandardError#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process_StandardError/CS/source.cs#1)] +[!code-vb[Process_StandardError#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_StandardError/VB/source.vb#1)] + \ No newline at end of file diff --git a/includes/remarks/System.Diagnostics/Process/StandardOutput.md b/includes/remarks/System.Diagnostics/Process/StandardOutput.md new file mode 100644 index 00000000000..31ea7823411 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/StandardOutput.md @@ -0,0 +1,38 @@ +When a writes text to its standard stream, that text is normally displayed on the console. By redirecting 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] +> To use , you must set to `false`, and you must 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 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. + +Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on 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 on 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 on each other to complete an operation, and neither can proceed. 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-csharp[Executable launched by Process.Start](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/write500lines.cs)] +[!code-vb[Executable launched by Process.Start](~/samples/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. + +[!code-csharp[Reading synchronously from a redirected output stream](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/stdoutput-sync.cs)] +[!code-vb[Reading synchronously from a redirected output stream](~/samples/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-csharp[Reading from a redirected output and error stream](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/stdoutput-async.cs)] +[!code-vb[Reading from a redirected output and error stream](~/samples/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. + +> [!NOTE] +> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. + +## Examples + +The following example runs the ipconfig.exe command and redirects its standard output to the example's console window. + +[!code-cpp[Process_StandardOutput#2](~/samples/snippets/cpp/VS_Snippets_CLR/Process_StandardOutput/CPP/process_standardoutput.cpp)] +[!code-csharp[Process_StandardOutput#2](~/samples/snippets/csharp/VS_Snippets_CLR/Process_StandardOutput/CS/process_standardoutput.cs)] +[!code-vb[Process_StandardOutput#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_StandardOutput/VB/process_standardoutput.vb)] + \ No newline at end of file diff --git a/includes/remarks/System.Diagnostics/Process/Start.md b/includes/remarks/System.Diagnostics/Process/Start.md new file mode 100644 index 00000000000..9ee51966b89 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Start.md @@ -0,0 +1,31 @@ +Use this overload to start a process resource and associate it with the current component. The return value `true` indicates that a new process resource was started. If the process resource specified by the member of the property is already running on the computer, no additional process resource is started. Instead, the running process resource is reused and `false` is returned. + +You can start a ClickOnce application by specifying 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 drive. + +> [!NOTE] +> If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the Properties window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. + +This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. + +The other overloads of the method are `static` members. You do not need to create an instance of the component before you call those overloads of the method. Instead, you can call for the class itself, and a new component is created if the process was started. Or, `null` is returned if a process was reused. The process resource is automatically associated with the new component that is returned by the method. + +The members can be used to duplicate the functionality of the `Run` dialog box of the Windows `Start` menu. Anything that can be typed into a command line can be started by setting the appropriate values in the property. The only property that must be set is the property. The property does not have to be an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. + +In the command line, you can specify actions to take for certain types of files. For example, you can print documents or edit text files. Specify these actions using the member of the property. For other types of files, you can specify command-line arguments when you start the file from the `Run` dialog box. For example, you can pass a URL as an argument if you specify your browser as the . These arguments can be specified in the property's member. + +If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. + +> [!NOTE] +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. + +Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + +A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + +## Examples + +The following example uses an instance of the class to start a process. + +[!code-cpp[Process.Start_instance#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp#1)] +[!code-csharp[Process.Start_instance#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_instance/CS/processstart.cs#1)] +[!code-vb[Process.Start_instance#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb#1)] diff --git a/includes/remarks/System.Diagnostics/Process/StartInfo.md b/includes/remarks/System.Diagnostics/Process/StartInfo.md new file mode 100644 index 00000000000..08c32d6f846 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/StartInfo.md @@ -0,0 +1,20 @@ + represents the set of parameters to use to start a process. When is called, the is used to specify the process to start. The only necessary member to set is the property. Starting a process by specifying the property is similar to typing the information in the **Run** dialog box of the Windows **Start** menu. Therefore, the property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the member. For example, you can set the property to either "Notepad.exe" or "Notepad". + + 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 drive. + + If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. + + You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . + + You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. + + When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. + +## Examples + + The following example populates a with the file to execute, the action performed on it and whether it should displays a user interface. For additional examples, refer to the reference pages for properties of the class. + + [!code-cpp[Process.Start_instance#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp#1)] + [!code-csharp[Process.Start_instance#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_instance/CS/processstart.cs#1)] + [!code-vb[Process.Start_instance#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb#1)] + \ No newline at end of file diff --git a/includes/remarks/System.Diagnostics/Process/Start_ProcessStartInfo.md b/includes/remarks/System.Diagnostics/Process/Start_ProcessStartInfo.md new file mode 100644 index 00000000000..99e0853e01a --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Start_ProcessStartInfo.md @@ -0,0 +1,33 @@ +Use this overload to start a process resource by specifying a instance. The overload associates the resource with a new object. + +> [!NOTE] +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. + +This overload lets you start a process without first creating a new instance. Using this overload with a parameter is an alternative to the explicit steps of creating a new instance, setting its properties, and calling for the instance. + +Using a instance as the parameter lets you call with the most control over what is passed into the call to start the process. If you need to pass only a file name or a file name and arguments, it is not necessary to create a new instance, although that is an option. The only property that must be set is the property. The property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. + +You can start a ClickOnce application by specifying 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 drive. + +If the and properties of the instance are set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If the property is `null`, the property must be in UPN format, *user*@*DNS_domain_name*. + +Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the start information for the process resource by using a instance. + +If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. + +> [!NOTE] +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. + +Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + +A note about apartment states in managed threads is necessary here. When is `true` on the `startInfo` parameter, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + +## Examples + +The following example first spawns an instance of Internet Explorer and displays the contents of the Favorites folder in the browser. It then starts some other instances of Internet Explorer and displays some specific pages or sites. Finally it starts Internet Explorer with the window being minimized while navigating to a specific site. + +For additional examples of other uses of this method, refer to the individual properties of the class. + +[!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] +[!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] +[!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] diff --git a/includes/remarks/System.Diagnostics/Process/Start_String.md b/includes/remarks/System.Diagnostics/Process/Start_String.md new file mode 100644 index 00000000000..8b59dd74a37 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Start_String.md @@ -0,0 +1,31 @@ +Use this overload to start a process resource by specifying its file name. The overload associates the resource with a new object. + +> [!NOTE] +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. + +This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. + +You can start a ClickOnce application by setting the `fileName` parameter 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 drive. + +Starting a process by specifying its file name is similar to typing the information in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". + +This overload does not allow command-line arguments for the process. If you need to specify one or more command-line arguments for the process, use the or overloads. + +Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start. + +If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. + +> [!NOTE] +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. + +Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + +A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + +## Examples + +The following example first spawns an instance of Internet Explorer and displays the contents of the Favorites folder in the browser. It then starts some other instances of Internet Explorer and displays some specific pages or sites. Finally it starts Internet Explorer with the window being minimized while navigating to a specific site. + +[!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] +[!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] +[!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] diff --git a/includes/remarks/System.Diagnostics/Process/Start_String_String.md b/includes/remarks/System.Diagnostics/Process/Start_String_String.md new file mode 100644 index 00000000000..752fe28218d --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Start_String_String.md @@ -0,0 +1,27 @@ +Use this overload to start a process resource by specifying its file name and command-line arguments. The overload associates the resource with a new object. + +> [!NOTE] +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. + +This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. + +Starting a process by specifying its file name and arguments is similar to typing the file name and command-line arguments in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. If the `fileName` parameter represents a command (.cmd) file, the `arguments` parameter must include either a "`/c`" or "`/k`" argument to specify whether the command window exits or remains after completion. + +Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start and command-line arguments to pass. + +If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. + +> [!NOTE] +> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. + +Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + +A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. + +## Examples + +The following example first spawns an instance of Internet Explorer and displays the contents of the Favorites folder in the browser. It then starts some other instances of Internet Explorer and displays some specific pages or sites. Finally it starts Internet Explorer with the window being minimized while navigating to a specific site. + +[!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] +[!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] +[!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] diff --git a/includes/remarks/System.Diagnostics/Process/Start_String_String_SecureString_String.md b/includes/remarks/System.Diagnostics/Process/Start_String_String_SecureString_String.md new file mode 100644 index 00000000000..cef11abfb78 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Start_String_String_SecureString_String.md @@ -0,0 +1,24 @@ + Use this overload to create a new process and its primary thread by specifying its file name, user name, password, and domain. The new process then runs the specified executable file in the security context of the specified credentials (user, domain, and password). + +> [!NOTE] +> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. + +> [!NOTE] +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. + + This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. + + Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. + +> [!NOTE] +> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. + + Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. + +## Examples + + The following code example shows the use of this overload to start an executable file and also demonstrates the throwing of a when an attempt is made to start an application associated with a nonexecutable file. + + [!code-csharp[System.Diagnostics.Process.Start#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.Start/CS/program.cs#1)] + [!code-vb[System.Diagnostics.Process.Start#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.Start/VB/program.vb#1)] + \ No newline at end of file diff --git a/includes/remarks/System.Diagnostics/Process/Start_String_String_String_SecureString_String.md b/includes/remarks/System.Diagnostics/Process/Start_String_String_String_SecureString_String.md new file mode 100644 index 00000000000..7d6564f09ea --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/Start_String_String_String_SecureString_String.md @@ -0,0 +1,16 @@ +Use this overload to create a new process and its primary thread by specifying its file name, command-line arguments, user name, password, and domain. The new process then runs the specified executable file in the security context of the specified credentials (user, domain, and password). + +> [!NOTE] +> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. + +> [!NOTE] +> If the address of the executable file to start is a URL, the process is not started and `null` is returned. + +This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. + +Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. + +> [!NOTE] +> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. + +Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. diff --git a/includes/remarks/System.Diagnostics/Process/SynchronizingObject.md b/includes/remarks/System.Diagnostics/Process/SynchronizingObject.md new file mode 100644 index 00000000000..15c8d0965a2 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/SynchronizingObject.md @@ -0,0 +1,17 @@ +When is `null`, methods that handle the event are called on a thread from the system thread pool. For more information about system thread pools, see . + +When the event is handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. + +If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control that contains the . For example, if you place a on a designer for `Form1` (which inherits from ) the property of is set to the instance of `Form1`: + +[!code-cpp[Process_SynchronizingObject#2](~/samples/snippets/cpp/VS_Snippets_CLR/Process_SynchronizingObject/CPP/remarks.cpp#2)] +[!code-csharp[Process_SynchronizingObject#2](~/samples/snippets/csharp/VS_Snippets_CLR/Process_SynchronizingObject/CS/remarks.cs#2)] +[!code-vb[Process_SynchronizingObject#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_SynchronizingObject/VB/remarks.vb#2)] + +Typically, this property is set when the component is placed inside a control or form, because those components are bound to a specific thread. + +## Examples +[!code-cpp[Process_SynchronizingObject#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process_SynchronizingObject/CPP/process_synchronizingobject.cpp#1)] +[!code-csharp[Process_SynchronizingObject#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process_SynchronizingObject/CS/process_synchronizingobject.cs#1)] +[!code-vb[Process_SynchronizingObject#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_SynchronizingObject/VB/process_synchronizingobject.vb#1)] + diff --git a/includes/remarks/System.Diagnostics/Process/WaitForExit.md b/includes/remarks/System.Diagnostics/Process/WaitForExit.md new file mode 100644 index 00000000000..474e4ff9c76 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/WaitForExit.md @@ -0,0 +1,16 @@ + makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. + +This method instructs the component to wait an infinite amount of time for the process and event handlers to exit. This can cause an application to stop responding. For example, if you call for a process that has a user interface, the request to the operating system to terminate the associated process might not be handled if the process is written to never enter its message loop. + +> [!NOTE] +> In .NET Framework 3.5 and earlier versions, the overload waits for milliseconds (approximately 24 days), not indefinitely. Also, those versions do not wait for the event handlers to exit if the full time is reached. + +This overload ensures that all processing has been completed, including the handling of asynchronous events for redirected standard output. You should use this overload after a call to the overload when standard output has been redirected to asynchronous event handlers. + +When an associated process exits (that is, when it is shut down by the operation system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. + +Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. + +## Examples + +See the Remarks section of the property reference page. diff --git a/includes/remarks/System.Diagnostics/Process/WaitForExit_Int32.md b/includes/remarks/System.Diagnostics/Process/WaitForExit_Int32.md new file mode 100644 index 00000000000..e881466d473 --- /dev/null +++ b/includes/remarks/System.Diagnostics/Process/WaitForExit_Int32.md @@ -0,0 +1,16 @@ + makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. + +This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. + +> [!NOTE] +> In .NET Framework 3.5 and earlier versions, if `milliseconds` is -1, the overload waits for milliseconds (approximately 24 days), not indefinitely. + +When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this method returns. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter after receiving a `true` from this overload. To help ensure that the event is handled correctly in Windows Forms applications, set the property. + +When an associated process exits (is shut down by the operating system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. + +Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. + +## Examples +See the code example for the property. + diff --git a/xml/System.Diagnostics/DataReceivedEventArgs.xml b/xml/System.Diagnostics/DataReceivedEventArgs.xml index 9fd8d0184d8..a53f11ed19a 100644 --- a/xml/System.Diagnostics/DataReceivedEventArgs.xml +++ b/xml/System.Diagnostics/DataReceivedEventArgs.xml @@ -34,23 +34,11 @@ Provides data for the and events. - or stream output of a process, you must create a method that handles the redirected stream output events. The event-handler method is called when the process writes to the redirected stream. The event delegate calls your event handler with an instance of . The property contains the text line that the process wrote to the redirected stream. - - - -## Examples - The following code example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. - - The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. - - [!code-cpp[Process_AsyncStreams#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/sort_async.cpp#1)] - [!code-csharp[Process_AsyncStreams#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/sort_async.cs#1)] - [!code-vb[Process_AsyncStreams#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/sort_async.vb#1)] - - ]]> + @@ -99,25 +87,11 @@ Gets the line of characters that was written to a redirected output stream. The line that was written by an associated to its redirected or stream. - or stream of a to your event handler, an event is raised each time the process writes a line to the redirected stream. The property is the line that the wrote to the redirected output stream. Your event handler can use the property to filter process output or write output to an alternate location. For example, you might create an event handler that stores all error output lines into a designated error log file. - - A line is defined as a sequence of characters followed by a line feed ("\n") or a carriage return immediately followed by a line feed ("\r\n"). The line characters are encoded using the default system ANSI code page. The property does not include the terminating carriage return or line feed. - - When the redirected stream is closed, a null line is sent to the event handler. Ensure your event handler checks the property appropriately before accessing it. For example, you can use the static method to validate the property in your event handler. - - - -## Examples - The following code example illustrates a simple event handler associated with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. - - [!code-cpp[Process_AsyncStreams#4](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/datareceivedevent.cpp#4)] - [!code-csharp[Process_AsyncStreams#4](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/datareceivedevent.cs#4)] - [!code-vb[Process_AsyncStreams#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/datareceivedevent.vb#4)] - - ]]> + diff --git a/xml/System.Diagnostics/DataReceivedEventHandler.xml b/xml/System.Diagnostics/DataReceivedEventHandler.xml index 79e930f350c..000775369af 100644 --- a/xml/System.Diagnostics/DataReceivedEventHandler.xml +++ b/xml/System.Diagnostics/DataReceivedEventHandler.xml @@ -42,25 +42,11 @@ A that contains the event data. Represents the method that will handle the event or event of a . - delegate, you identify the method that will handle the event. To associate the event with your event handler, add an instance of the delegate to the event. The event handler is called whenever the event occurs, unless you remove the delegate. For more information about event-handler delegates, see [Handling and Raising Events](/dotnet/standard/events/). - - To asynchronously collect the redirected or stream output of a process, add your event handler to the or event. These events are raised each time the process writes a line to the corresponding redirected stream. When the redirected stream is closed, a null line is sent to the event handler. Ensure that your event handler checks for this condition before accessing the property. For example, you can use the `static` method to validate the property in your event handler. - - - -## Examples - The following code example illustrates how to perform asynchronous read operations on the redirected stream of the **sort** command. The **sort** command is a console application that reads and sorts text input. - - The example creates a delegate for the `SortOutputHandler` event handler and associates the delegate with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. - - [!code-cpp[Process_AsyncStreams#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/sort_async.cpp#1)] - [!code-csharp[Process_AsyncStreams#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/sort_async.cs#1)] - [!code-vb[Process_AsyncStreams#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/sort_async.vb#1)] - - ]]> + diff --git a/xml/System.Diagnostics/Process.xml b/xml/System.Diagnostics/Process.xml index 5545557c71f..3ca2ea533bf 100644 --- a/xml/System.Diagnostics/Process.xml +++ b/xml/System.Diagnostics/Process.xml @@ -84,63 +84,11 @@ Provides access to local and remote processes and enables you to start and stop local system processes. - component provides access to a process that is running on a computer. A process, in the simplest terms, is a running app. A thread is the basic unit to which the operating system allocates processor time. A thread can execute any part of the code of the process, including parts currently being executed by another thread. - - The component is a useful tool for starting, stopping, controlling, and monitoring apps. You can use the component, to obtain a list of the processes that are running, or you can start a new process. A component is used to access system processes. After a component has been initialized, it can be used to obtain information about the running process. Such information includes the set of threads, the loaded modules (.dll and .exe files), and performance information such as the amount of memory the process is using. - - This type implements the interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - -> [!NOTE] -> 32-bit processes cannot access the modules of a 64-bit process. If you try to get information about a 64-bit process from a 32-bit process, you will get a exception. A 64-bit process, on the other hand, can access the modules of a 32-bit process. - - The process component obtains information about a group of properties all at once. After the component has obtained information about one member of any group, it will cache the values for the other properties in that group and not obtain new information about the other members of the group until you call the method. Therefore, a property value is not guaranteed to be any newer than the last call to the method. The group breakdowns are operating-system dependent. - - If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - - A system process is uniquely identified on the system by its process identifier. Like many Windows resources, a process is also identified by its handle, which might not be unique on the computer. A handle is the generic term for an identifier of a resource. The operating system persists the process handle, which is accessed through the property of the component, even when the process has exited. Thus, you can get the process's administrative information, such as the (usually either zero for success or a nonzero error code) and the . Handles are an extremely valuable resource, so leaking handles is more virulent than leaking memory. - -> [!NOTE] -> This class contains a link demand and an inheritance demand at the class level that applies to all members. A is thrown when either the immediate caller or the derived class does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). - - -## .NET Core Notes - In the .NET Framework, the class by default uses encodings, which are typically code page encodings, for the input, output, and error streams. For example code, on systems whose culture is English (United States), code page 437 is the default encoding for the class. However, .NET Core may make only a limited subset of these encodings available. If this is the case, it uses as the default encoding. - - If a object depends on specific code page encodings, you can still make them available by doing the following *before* you call any methods: - -1. Add a reference to the System.Text.Encoding.CodePages.dll assembly to your project. - -2. Retrieve the object from the property. - -3. Pass the object to the method to make the additional encodings supported by the encoding provider available. - - The class will then automatically use the default system encoding rather than UTF8, provided that you have registered the encoding provider before calling any methods. - - - -## Examples - The following example uses an instance of the class to start a process. - - [!code-cpp[Process.Start_instance#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp#1)] - [!code-csharp[Process.Start_instance#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_instance/CS/processstart.cs#1)] - [!code-vb[Process.Start_instance#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb#1)] - - The following example uses the class itself and a static method to start a process. - - [!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] - [!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] - [!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] - - The following F# example defines a `runProc` function that starts a process, captures all output and error information, and records the number of milliseconds that the process has run. The `runProc` function has three parameters: the name of application to launch, the arguments to supply to the application, and the starting directory. - - [!code-fsharp[System.Diagnostics.Process#1](~/samples/snippets/fsharp/VS_Snippets_CLR_System/system.diagnostics.process/fs/Start1.fs#1)] - - The code for the `runProc` function was written by [ImaginaryDevelopment](http://fssnip.net/authors/ImaginaryDevelopment) and is available under the [Microsoft Public License](https://opensource.org/licenses/ms-pl). - - ]]> + @@ -181,22 +129,11 @@ Initializes a new instance of the class. - property, the default is the local computer, ("."). - - You have two options for associating a new component with a process on the computer. The first option is to use the constructor to create the component, set the appropriate members of the property and call to associate the with a new system process. The second option is to associate the with a running system process by using or one of the return values. - - If you use a `static` overload of the method to start a new system process, the method creates a new component and associates it with the process. - - When the property is set to its default value, `true`, you can start applications and documents in a way that is similar to using the `Run` dialog box of the Windows `Start` menu. When is `false`, you can start only executables. - - Any executable file that you can call from the command line can be started in one of two ways: by setting the appropriate members of the property and calling the method with no parameters, or by passing the appropriate parameter to the `static` member. - - You can create a component by using the constructor, one of the static overloads, or any of the , , or methods. After you have done so, you have a view into the associated process. This is not a dynamic view that updates itself automatically when the process properties have changed in memory. Instead, you must call for the component to update the property information in your application. - - ]]> + @@ -253,34 +190,11 @@ Gets the base priority of the associated process. The base priority, which is computed from the of the associated process. - method first. + of the process is the starting priority for threads created within the associated process. You can view information about the base priority through the System Monitor's Priority Base counter. - - Based on the time elapsed or other boosts, the operating system can change the base priority when a process should be placed ahead of others. - - The property lets you view the starting priority assigned to a process. However, because it is read-only, you cannot use the to set the priority of the process. To change the priority, use the property. The is viewable using the System Monitor, while the is not. Both the and the can be viewed programmatically. The following table shows the relationship between values and values. - -|BasePriority|PriorityClass| -|------------------|-------------------| -|4|| -|8|| -|13|| -|24|| - - - -## Examples - The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. - - [!code-cpp[Diag_Process_MemoryProperties64#1](~/samples/snippets/cpp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CPP/source.cpp#1)] - [!code-csharp[Diag_Process_MemoryProperties64#1](~/samples/snippets/csharp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CS/source.cs#1)] - [!code-vb[Diag_Process_MemoryProperties64#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Diag_Process_MemoryProperties64/VB/source.vb#1)] - - ]]> +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/BasePriority.md)] + + ]]> The process has exited. @@ -332,42 +246,11 @@ Begins asynchronous read operations on the redirected stream of the application. - 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 the 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. - - Follow these steps to perform asynchronous read operations on for a : - -1. Set to `false`. - -2. Set to `true`. - -3. Add your event handler to the event. The event handler must match the delegate signature. - -4. Start the . - -5. Call for the . This call starts asynchronous read operations on . - - When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. - - You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. - -> [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. - - - -## Examples - The following example uses the `net view` command to list the available network resources on a remote computer. The user supplies the target computer name as a command-line argument. The user can also supply a file name for error output. The example collects the output of the net command, waits for the process to finish, and then writes the output results to the console. If the user supplies the optional error file, the example writes errors to the file. - - [!code-cpp[Process_AsyncStreams#2](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/net_async.cpp#2)] - [!code-csharp[Process_AsyncStreams#2](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/net_async.cs#2)] - [!code-vb[Process_AsyncStreams#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/net_async.vb#2)] - - ]]> + The property is . @@ -425,44 +308,11 @@ Begins asynchronous read operations on the redirected stream of the application. - 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 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. - - Follow these steps to perform asynchronous read operations on for a : - -1. Set to `false`. - -2. Set to `true`. - -3. Add your event handler to the event. The event handler must match the delegate signature. - -4. Start the . - -5. Call for the . This call starts asynchronous read operations on . - - When asynchronous read operations start, the event handler is called each time the associated writes a line of text to its stream. - - You can cancel an asynchronous read operation by calling . The read operation can be canceled by the caller or by the event handler. After canceling, you can call again to resume asynchronous read operations. - -> [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. - - - -## Examples - The following example illustrates how to perform asynchronous read operations on the redirected stream of the `sort` command. The `sort` command is a console application that reads and sorts text input. - - The example creates an event delegate for the `SortOutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and writes the text to the screen. - - [!code-cpp[Process_AsyncStreams#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/sort_async.cpp#1)] - [!code-csharp[Process_AsyncStreams#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/sort_async.cs#1)] - [!code-vb[Process_AsyncStreams#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/sort_async.vb#1)] - - ]]> + The property is . @@ -520,44 +370,11 @@ Cancels the asynchronous read operation on the redirected stream of an application. - starts an asynchronous read operation on the stream. ends the asynchronous read operation. - - After canceling, you can resume the asynchronous read operation by calling again. - - When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to will be lost. If you re-enable the event handler with a call to , asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: - -```csharp -// At this point the DataReceivedEventHandler(ErrorHandler1) -// has executed a CancelErrorRead. - -// Remove the prior event handler. -process.ErrorDataReceived -= - new DataReceivedEventHandler(ErrorHandler1); - -// Register a new event handler. -process.ErrorDataReceived += - new DataReceivedEventHandler(ErrorHandler2); - -// Call the corresponding BeginErrorReadLine. -process.BeginErrorReadLine(); -``` - -> [!NOTE] -> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . - - - -## Examples - The following example starts the `nmake` command with user supplied arguments. The error and output streams are read asynchronously; the collected text lines are displayed to the console as well as written to a log file. If the command output exceeds a specified number of lines, the asynchronous read operations are canceled. - - [!code-cpp[Process_AsyncStreams#3](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/nmake_async.cpp#3)] - [!code-csharp[Process_AsyncStreams#3](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/nmake_async.cs#3)] - [!code-vb[Process_AsyncStreams#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/nmake_async.vb#3)] - - ]]> + The stream is not enabled for asynchronous read operations. @@ -607,44 +424,11 @@ process.BeginErrorReadLine(); Cancels the asynchronous read operation on the redirected stream of an application. - starts an asynchronous read operation on the stream. ends the asynchronous read operation. - - After canceling, you can resume asynchronous read operations by calling again. - - When you call , all in-progress read operations for are completed and then the event handler is disabled. All further redirected output to is saved in a buffer. If you re-enable the event handler with a call to , the saved output is sent to the event handler and asynchronous read operations resume. If you want to change the event handler before resuming asynchronous read operations, you must remove the existing event handler before adding the new event handler: - -```csharp -// At this point the DataReceivedEventHandler(OutputHandler1) -// has executed a CancelOutputRead. - -// Remove the prior event handler. -process.OutputDataReceived -= - new DataReceivedEventHandler(OutputHandler1); - -// Register a new event handler. -process.OutputDataReceived += - new DataReceivedEventHandler(OutputHandler2); - -// Call the corresponding BeginOutputReadLine. -process.BeginOutputReadLine(); -``` - -> [!NOTE] -> You cannot mix asynchronous and synchronous read operations on the redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. If you cancel an asynchronous read operation on and then need to read from the stream again, you must use to resume asynchronous read operations. Do not follow with a call to the synchronous read methods of such as , , or . - - - -## Examples - The following example starts the `nmake` command with user supplied arguments. The error and output streams are read asynchronously; the collected text lines are displayed to the console as well as written to a log file. If the command output exceeds a specified number of lines, the asynchronous read operations are canceled. - - [!code-cpp[Process_AsyncStreams#3](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/nmake_async.cpp#3)] - [!code-csharp[Process_AsyncStreams#3](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/nmake_async.cs#3)] - [!code-vb[Process_AsyncStreams#3](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/nmake_async.vb#3)] - - ]]> + The stream is not enabled for asynchronous read operations. @@ -695,9 +479,7 @@ process.BeginOutputReadLine(); > [!NOTE] > The method calls . Placing the object in a `using` block disposes of resources without the need to call . - - - + ## Examples The following example starts an instance of Notepad. It then retrieves the physical memory usage of the associated process at 2-second intervals for a maximum of 10 seconds. The example detects whether the process exits before 10 seconds have elapsed. The example closes the process if it is still running after 10 seconds. @@ -753,9 +535,7 @@ process.BeginOutputReadLine(); Data edited by the process or resources allocated to the process can be lost if you call . causes an abnormal process termination, and should be used only when necessary. enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. If fails, you can use to terminate the process. is the only way to terminate processes that do not have graphical interfaces. You can call and only for processes that are running on the local computer. You cannot cause processes on remote computers to exit. You can only view information for processes running on remote computers. - - - + ## Examples The following example starts an instance of Notepad. It then retrieves the physical memory usage of the associated process at 2 second intervals for a maximum of 10 seconds. The example detects whether the process exits before 10 seconds have elapsed. The example closes the process if it is still running after 10 seconds. @@ -906,29 +686,11 @@ process.BeginOutputReadLine(); if the event should be raised when the associated process is terminated (through either an exit or a call to ); otherwise, . The default is . Note that the event is raised even if the value of is when the process exits during or before the user performs a check. - property suggests whether the component should be notified when the operating system has shut down a process. The property is used in asynchronous processing to notify your application that a process has exited. To force your application to synchronously wait for an exit event (which interrupts processing of the application until the exit event has occurred), use the method. - -> [!NOTE] -> If you're using Visual Studio and double-click a component in your project, an event delegate and event handler are automatically generated. Additional code sets the property to `false`. You must change this property to `true` for your event handler to execute when the associated process exits. - -If the component's value is `true`, or when is `false` and a check is invoked by the component, the component can access the administrative information for the associated process, which remains stored by the operating system. Such information includes the and the . - -After the associated process exits, the of the component no longer points to an existing process resource. Instead, it can only be used to access the operating system's information about the process resource. The operating system is aware that there are handles to exited processes that haven't been released by components, so it keeps the and information in memory. - -There's a cost associated with watching for a process to exit. If is `true`, the event is raised when the associated process terminates. Your procedures for the event run at that time. - -Sometimes, your application starts a process but doesn't require notification of its closure. For example, your application can start Notepad to allow the user to perform text editing but make no further use of the Notepad application. You can choose to avoid notification when the process exits because it's not relevant to the continued operation of your application. Setting to `false` can save system resources. + property to cause the process to raise the event when it exits. The event handler displays process information. +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/EnableRaisingEvents.md)] -[!code-csharp[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/CS/processexitedevent.cs#1)] -[!code-vb[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/VB/processexitedevent.vb#1)] - - ]]> + ]]> @@ -1033,26 +795,11 @@ The following code example creates a process that prints a file. It sets the Occurs when an application writes to its redirected stream. - event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. - - The event only occurs during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . - -> [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. Note that specifying a timeout by using the overload does *not* ensure the output buffer has been flushed. - - - -## Examples - The following example uses the `net view` command to list the available network resources on a remote computer. The user supplies the target computer name as a command-line argument. The user can also supply a file name for error output. The example collects the output of the net command, waits for the process to finish, and then writes the output results to the console. If the user supplies the optional error file, the example writes errors to the file. - - [!code-cpp[Process_AsyncStreams#2](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/net_async.cpp#2)] - [!code-csharp[Process_AsyncStreams#2](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/net_async.cs#2)] - [!code-vb[Process_AsyncStreams#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/net_async.vb#2)] - - ]]> + @@ -1114,34 +861,11 @@ The following code example creates a process that prints a file. It sets the Gets the value that the associated process specified when it terminated. The code that the associated process specified when it terminated. - to get the status that the system process returned when it exited. You can use the exit code much like an integer return value from a `main()` procedure. - - The value for a process reflects the specific convention implemented by the application developer for that process. If you use the exit code value to make decisions in your code, be sure that you know the exit code convention used by the application process. - - Developers usually indicate a successful exit by an value of zero, and designate errors by nonzero values that the calling method can use to identify the cause of an abnormal process termination. It is not necessary to follow these guidelines, but they are the convention. - - If you try to get the before the process has exited, the attempt throws an exception. Examine the property first to verify whether the associated process has terminated. - -> [!NOTE] -> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . - - You can use the or the method to cause an associated process to exit. - - There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification relies on calling the method to pause the processing of your application until the associated component exits. Asynchronous notification relies on the event. When using asynchronous notification, must be set to `true` for the component to receive notification that the process has exited. - - - -## Examples - The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. - - [!code-cpp[Diag_Process_MemoryProperties64#1](~/samples/snippets/cpp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CPP/source.cpp#1)] - [!code-csharp[Diag_Process_MemoryProperties64#1](~/samples/snippets/csharp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CS/source.cs#1)] - [!code-vb[Diag_Process_MemoryProperties64#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Diag_Process_MemoryProperties64/VB/source.vb#1)] - - ]]> + The process has not exited. @@ -1204,29 +928,11 @@ The following code example creates a process that prints a file. It sets the Occurs when a process exits. - event indicates that the associated process exited. This occurrence means either that the process terminated (aborted) or successfully closed. This event can occur only if the value of the property is `true`. - - There are two ways of being notified when the associated process exits: synchronously and asynchronously. Synchronous notification means calling the method to block the current thread until the process exits. Asynchronous notification uses the event, which allows the calling thread to continue execution in the meantime. In the latter case, must be set to `true` for the calling application to receive the Exited event. - - When the operating system shuts down a process, it notifies all other processes that have registered handlers for the Exited event. At this time, the handle of the process that just exited can be used to access some properties such as and that the operating system maintains until it releases that handle completely. - -> [!NOTE] -> Even if you have a handle to an exited process, you cannot call again to reconnect to the same process. Calling automatically releases the associated process and connects to a process with the same file but an entirely new . - - For more information about the use of the event in Windows Forms applications, see the property. - - - -## Examples - The following code example creates a process that prints a file. It raises the event when the process exits because the property was set when the process was created. The event handler displays process information. - - [!code-csharp[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/CS/processexitedevent.cs#1)] - [!code-vb[System.Diagnostics.Process.EnableExited#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.EnableExited/VB/processexitedevent.vb#1)] - - ]]> + @@ -1287,9 +993,7 @@ The following code example creates a process that prints a file. It sets the property throws an exception. Use before getting the property to determine whether the associated process has terminated. - - - + ## Examples The following code example creates a process that prints a file. The process raises the event when it exits, and the event handler displays the property and other process information. @@ -1345,9 +1049,7 @@ The following code example creates a process that prints a file. It sets the instance and associate it with the process resource on the local computer. Like the similar , , and methods, associates an existing resource with a new component. - - - + ## Examples The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. @@ -1417,23 +1119,11 @@ The following code example creates a process that prints a file. It sets the Returns a new component, given the identifier of a process on the local computer. A component that is associated with the local process resource identified by the parameter. - component and associate it with a process resource on the local computer. The process resource must already exist on the computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. - - On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. - - The `processId` parameter is an (a 32-bit signed integer), although the underlying Windows API uses a `DWORD` (an unsigned 32-bit integer) for similar APIs. This is for historical reasons. - -## Examples - The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. - - [!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] - [!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] - [!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] - - ]]> + The process specified by the parameter is not running. The identifier might be expired. The process was not started by this object. @@ -1490,25 +1180,11 @@ The following code example creates a process that prints a file. It sets the Returns a new component, given a process identifier and the name of a computer on the network. A component that is associated with a remote process resource identified by the parameter. - component and associate it with a process resource on a remote computer on the network. The process resource must already exist on the specified computer, because does not create a system resource, but rather associates a resource with an application-generated component. A process can be retrieved only for a process that is currently running on the computer. After the process terminates, throws an exception if you pass it an expired identifier. - - On any particular computer, the identifier of a process is unique. returns one process at most. If you want to get all the processes running a particular application, use . If multiple processes exist on the computer running the specified application, returns an array containing all the associated processes. You can query each of these processes in turn for its identifier. The process identifier can be viewed in the `Processes` panel of the Windows Task Manager. The `PID` column displays the process identifier that is assigned to a process. - - If you do not specify a `machineName`, the local computer is used. Alternatively, you can specify the local computer by setting `machineName` to the value "." or to an empty string (""). - - The `processId` parameter is an (a 32-bit signed integer), although the underlying Windows API uses a `DWORD` (an unsigned 32-bit integer) for similar APIs. This is for historical reasons. - -## Examples - The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. - - [!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] - [!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] - [!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] - - ]]> + The process specified by the parameter is not running. The identifier might be expired. @@ -1576,26 +1252,11 @@ The following code example creates a process that prints a file. It sets the Creates a new component for each process resource on the local computer. An array of type that represents all the process resources running on the local computer. - components and associate them with all the process resources on the local computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. - - If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. - -> [!NOTE] -> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . - - - -## Examples - The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. - - [!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] - [!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] - [!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] - - ]]> + @@ -1648,28 +1309,11 @@ The following code example creates a process that prints a file. It sets the Creates a new component for each process resource on the specified computer. An array of type that represents all the process resources running on the specified computer. - components and associate them with all the process resources on the specified (usually remote) computer. The process resources must already exist on the local computer, because does not create system resources but rather associates resources with application-generated components. Because the operating system itself is running background processes, this array is never empty. - - If you do not want to retrieve all the processes running on the computer, you can restrict their number by using the or method. creates a component that is associated with the process identified on the system by the process identifier that you pass to the method. creates an array of components whose associated process resources share the executable file you pass to the method. - - This overload of the method is generally used to retrieve the list of process resources running on a remote computer on the network, but you can specify the local computer by passing ".". - -> [!NOTE] -> Multiple Windows services can be loaded within the same instance of the Service Host process (svchost.exe). GetProcesses does not identify those individual services; for that, see . - - - -## Examples - The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. - - [!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] - [!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] - [!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] - - ]]> + The parameter syntax is invalid. It might have length zero (0). The parameter is . @@ -1738,25 +1382,11 @@ The following code example creates a process that prints a file. It sets the Creates an array of new components and associates them with all the process resources on the local computer that share the specified process name. An array of type that represents the process resources running the specified application or file. - components and associate them with all the process resources that are running the same executable file on the local computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. - - The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. - - Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. - - - -## Examples - The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. - - [!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] - [!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] - [!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] - - ]]> + There are problems accessing the performance counter APIs used to get process information. This exception is specific to Windows NT, Windows 2000, and Windows XP. @@ -1813,29 +1443,11 @@ The following code example creates a process that prints a file. It sets the Creates an array of new components and associates them with all the process resources on a remote computer that share the specified process name. An array of type that represents the process resources running the specified application or file. - components and associate them with all the process resources that are running the same executable file on the specified computer. The process resources must already exist on the computer, because does not create system resources but rather associates them with application-generated components. A `processName` can be specified for an executable file that is not currently running on the local computer, so the array the method returns can be empty. - - The process name is a friendly name for the process, such as Outlook, that does not include the .exe extension or the path. is helpful for getting and manipulating all the processes that are associated with the same executable file. For example, you can pass an executable file name as the `processName` parameter, in order to shut down all the running instances of that executable file. - - Although a process is unique to a single process resource on the system, multiple processes on the local computer can be running the application specified by the `processName` parameter. Therefore, returns one process at most, but returns an array containing all the associated processes. If you need to manipulate the process using standard API calls, you can query each of these processes in turn for its identifier. You cannot access process resources through the process name alone but, once you have retrieved an array of components that have been associated with the process resources, you can start, terminate, and otherwise manipulate the system resources. - - You can use this overload to get processes on the local computer as well as on a remote computer. Use "." to specify the local computer. Another overload exists that uses the local computer by default. - - You can access processes on remote computers only to view information, such as statistics, about the processes. You cannot close, terminate (using ), or start processes on remote computers. - - - -## Examples - The following example retrieves information of the current process, processes running on the local computer, all instances of Notepad running on the local computer, and a specific process on the local computer. It then retrieves information for the same processes on a remote computer. - - [!code-cpp[Process.GetProcesses_noexception#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.GetProcesses_noexception/CPP/processstaticget.cpp#1)] - [!code-csharp[Process.GetProcesses_noexception#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.GetProcesses_noexception/CS/processstaticget.cs#1)] - [!code-vb[Process.GetProcesses_noexception#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.GetProcesses_noexception/VB/processstaticget.vb#1)] - - ]]> + The parameter syntax is invalid. It might have length zero (0). The parameter is . @@ -2051,26 +1663,11 @@ There are problems accessing the performance counter APIs used to get process in if the operating system process referenced by the component has terminated; otherwise, . - indicates that the associated process has terminated, either normally or abnormally. You can request or force the associated process to exit by calling or . If a handle is open to the process, the operating system releases the process memory when the process has exited, but retains administrative information about the process, such as the handle, exit code, and exit time. To get this information, you can use the and properties. These properties are populated automatically for processes that were started by this component. The administrative information is released when all the components that are associated with the system process are destroyed and hold no more handles to the exited process. - - A process can terminate independently of your code. If you started the process using this component, the system updates the value of automatically, even if the associated process exits independently. - -> [!NOTE] -> When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this property returns `true`. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter before checking . - - - -## Examples - The following example starts an instance of Notepad. It then retrieves the physical memory usage of the associated process at 2 second intervals for a maximum of 10 seconds. The example detects whether the process exits before 10 seconds have elapsed. The example closes the process if it is still running after 10 seconds. - - [!code-cpp[process_refresh#1](~/samples/snippets/cpp/VS_Snippets_CLR/process_refresh/CPP/process_refresh.cpp#1)] - [!code-csharp[process_refresh#1](~/samples/snippets/csharp/VS_Snippets_CLR/process_refresh/CS/process_refresh.cs#1)] - [!code-vb[process_refresh#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_refresh/VB/process_refresh.vb#1)] - - ]]> + There is no process associated with the object. The exit code for the process could not be retrieved. @@ -2131,26 +1728,11 @@ There are problems accessing the performance counter APIs used to get process in Gets the unique identifier for the associated process. The system-generated unique identifier of the process that is referenced by this instance. - is not valid if the associated process is not running. Therefore, you should ensure that the process is running before attempting to retrieve the property. Until the process terminates, the process identifier uniquely identifies the process throughout the system. - - You can connect a process that is running on a local or remote computer to a new instance by passing the process identifier to the method. is a `static` method that creates a new component and sets the property for the new instance automatically. - - Process identifiers can be reused by the system. The property value is unique only while the associated process is running. After the process has terminated, the system can reuse the property value for an unrelated process. - - Because the identifier is unique on the system, you can pass it to other threads as an alternative to passing a instance. This action can save system resources yet guarantee that the process is correctly identified. - - - -## Examples - The following example demonstrates how to obtain the for all running instances of an application. The code creates a new instance of Notepad, lists all the instances of Notepad, and then allows the user to enter the number to remove a specific instance. - - [!code-csharp[System.Diagnostics.Process.Id#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.Id/CS/program.cs#1)] - [!code-vb[System.Diagnostics.Process.Id#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.Id/VB/program.vb#1)] - - ]]> + The process's property has not been set. @@ -2165,39 +1747,11 @@ There are problems accessing the performance counter APIs used to get process in Forces termination of the underlying process. - only requests a termination. -When a process with a graphical interface is executing, its message loop is in a wait state. -The message loop executes every time a Windows message is sent to the process by the operating system. -Calling sends a request to close the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application. -The request to exit the process by calling does not force the application to quit. -The application can ask for user verification before quitting, or it can refuse to quit. -To force the application to quit, use the `Kill` method. + is identical to that of a user closing an application's main window using the system menu. -Therefore, the request to exit the process by closing the main window does not force the application to quit immediately. - -> [!NOTE] -> The method executes asynchronously. -> After calling the `Kill` method, call the method to wait for the process to exit, or check the property to determine if the process has exited. +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/Kill.md)] -> [!NOTE] -> The method and the property do not reflect the status of descendant processes. -> When `Kill(entireProcessTree: true)` is used, and will indicate that exiting has completed after the given process exits, even if all descendants have not yet exited. - -Data edited by the process or resources allocated to the process can be lost if you call `Kill`. -`Kill` causes an abnormal process termination and should be used only when necessary. - enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. -If fails, you can use `Kill` to terminate the process. -`Kill` is the only way to terminate processes that do not have graphical interfaces. - -You can call `Kill` and only for processes that are running on the local computer. -You cannot cause processes on remote computers to exit. You can only view information for processes running on remote computers. - - ]]> + ]]> @@ -2398,9 +1952,7 @@ The calling process is a member of the associated process' descendant tree. [!NOTE] > When the associated process is executing on the local machine, this property returns a period (".") for the machine name. You should use the property to get the correct machine name. - - - + ## Examples To use the following example you must first start at least one instance of Notepad on a remote computer. The example requests the name of the remote computer on which Notepad is running, and then displays the respective , , and properties for each instance. @@ -2618,9 +2170,7 @@ The calling process is a member of the associated process' descendant tree. [!NOTE] > The main window is the window that currently has the focus; note that this might not be the primary window for the process. You must use the method to refresh the object to get the most up to date main window handle if it has changed. - - - + ## Examples The following example starts an instance of Notepad and retrieves the caption of the main window of the process. @@ -3009,9 +2559,7 @@ The calling process is a member of the associated process' descendant tree. If you are using the Visual Studio environment, an event handler delegate (AddOnExited) and an event-handling method (Process1_Exited) are created for you when you drag a component onto a form and double-click the icon. The code you create to run when the event occurs is entered into the Process1_Exited procedure. You do not need to create the member, because it is implemented for you. Raising an event invokes the event handler through a delegate. For an overview, see [Handling and Raising Events](/dotnet/standard/events/). - - - + ## Examples The following example shows how to use the method in a derived class. @@ -3133,28 +2679,11 @@ The calling process is a member of the associated process' descendant tree. Occurs each time an application writes a line to its redirected stream. - event indicates that the associated has written a line that's terminated with a newline (carriage return (CR), line feed (LF), or CR+LF) to its redirected stream. - - The event is enabled during asynchronous read operations on . To start asynchronous read operations, you must redirect the stream of a , add your event handler to the event, and call . Thereafter, the event signals each time the process writes a line to the redirected stream, until the process exits or calls . - -> [!NOTE] -> The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. - - - -## Examples - The following example illustrates how to perform asynchronous read operations on the redirected stream of the `ipconfig` command. - - The example creates an event delegate for the `OutputHandler` event handler and associates it with the event. The event handler receives text lines from the redirected stream, formats the text, and saves it in an output string that's later shown in the example's console window. - - [!code-cpp[Process_AsyncStreams#4](~/samples/snippets/cpp/VS_Snippets_CLR/process_asyncstreams/CPP/datareceivedevent.cpp#4)] - [!code-csharp[Process_AsyncStreams#4](~/samples/snippets/csharp/VS_Snippets_CLR/process_asyncstreams/CS/datareceivedevent.cs#4)] - [!code-vb[Process_AsyncStreams#4](~/samples/snippets/visualbasic/VS_Snippets_CLR/process_asyncstreams/VB/datareceivedevent.vb#4)] - - ]]> + @@ -3286,9 +2815,7 @@ The calling process is a member of the associated process' descendant tree. property. This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Page File Bytes** performance counter for the process. - - - + ## Examples The following code example starts an instance of the Notepad application, and then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays its exit code and peak memory statistics. @@ -3423,9 +2950,7 @@ The calling process is a member of the associated process' descendant tree. property. This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Pool Paged Bytes** performance counter for the process. - - - + ## Examples The following code example starts an instance of the Notepad application. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays its exit code and peak memory statistics. @@ -3568,9 +3093,7 @@ The calling process is a member of the associated process' descendant tree. method first. +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/PriorityClass.md)] - A process priority class encompasses a range of thread priority levels. Threads with different priorities that are running in the process run relative to the priority class of the process. Win32 uses four priority classes with seven base priority levels per class. These process priority classes are captured in the enumeration, which lets you set the process priority to , , , , , or . Based on the time elapsed or other boosts, the base priority level can be changed by the operating system when a process needs to be put ahead of others for access to the processor. In addition, you can set the to temporarily boost the priority level of threads that have been taken out of the wait state. The priority is reset when the process returns to the wait state. - - The property lets you view the starting priority that is assigned to a process. However, because it is read-only, you cannot use the property to set the priority of a process. To change the priority, use the property, which gets or sets the overall priority category for the process. - - The priority class cannot be viewed using System Monitor. The following table shows the relationship between the and values. - -|BasePriority|PriorityClass| -|------------------|-------------------| -|4|| -|8|| -|13|| -|24|| - - - -## Examples - The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. - - [!code-cpp[Diag_Process_MemoryProperties64#1](~/samples/snippets/cpp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CPP/source.cpp#1)] - [!code-csharp[Diag_Process_MemoryProperties64#1](~/samples/snippets/csharp/VS_Snippets_CLR/Diag_Process_MemoryProperties64/CS/source.cs#1)] - [!code-vb[Diag_Process_MemoryProperties64#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Diag_Process_MemoryProperties64/VB/source.vb#1)] - - ]]> + ]]> Process priority information could not be set or retrieved from the associated process resource. @@ -4156,9 +3652,7 @@ The calling process is a member of the associated process' descendant tree. method first. This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Private Bytes** performance counter for the process. - - - + ## Examples The following code example starts an instance of the Notepad application. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays its exit code and peak memory statistics. @@ -4358,26 +3852,11 @@ The calling process is a member of the associated process' descendant tree.Gets or sets the processors on which the threads in this process can be scheduled to run. A bitmask representing the processors that the threads in the associated process can run on. The default depends on the number of processors on the computer. The default value is 2 n -1, where n is the number of processors. - method first. - - In Windows 2000 and later, a thread in a process can migrate from processor to processor, with each migration reloading the processor cache. Under heavy system loads, specifying which processor should run a specific thread can improve performance by reducing the number of times the processor cache is reloaded. The association between a processor and a thread is called the processor affinity. - - Each processor is represented as a bit. Bit 0 is processor one, bit 1 is processor two, and so forth. If you set a bit to the value 1, the corresponding processor is selected for thread assignment. When you set the value to zero, the operating system's scheduling algorithms set the thread's affinity. When the value is set to any nonzero value, the value is interpreted as a bitmask that specifies those processors eligible for selection. - - The following table shows a selection of values for an eight-processor system. - -|Bitmask|Binary value|Eligible processors| -|-------------|------------------|-------------------------| -|0x0001|00000000 00000001|1| -|0x0003|00000000 00000011|1 and 2| -|0x0007|00000000 00000111|1, 2 and 3| -|0x0009|00000000 00001001|1 and 4| -|0x007F|00000000 01111111|1, 2, 3, 4, 5, 6 and 7| - - ]]> + information could not be set or retrieved from the associated process resource. @@ -4434,9 +3913,7 @@ The calling process is a member of the associated process' descendant tree. is called, the first request for information about each property causes the process component to obtain a new value from the associated process. When a component is associated with a process resource, the property values of the are immediately populated according to the status of the associated process. If the information about the associated process subsequently changes, those changes are not reflected in the component's cached values. The component is a snapshot of the process resource at the time they are associated. To view the current values for the associated process, call the method. - - - + ## Examples The following example starts an instance of Notepad. It then retrieves the physical memory usage of the associated process at 2 second intervals for a maximum of 10 seconds. The example detects whether the process exits before 10 seconds have elapsed. The example closes the process if it is still running after 10 seconds. @@ -4509,9 +3986,7 @@ The calling process is a member of the associated process' descendant tree. property contacts the user interface to determine whether the process is responding to user input. If the interface does not respond immediately, the property returns `false`. Use this property to determine whether the interface of the associated process has stopped responding. If the process does not have a , this property returns `true`. - - - + ## Examples The following example starts an instance of Notepad. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays the process's exit code. @@ -4695,52 +4170,14 @@ The calling process is a member of the associated process' descendant tree.System.IO.StreamReader - Gets a stream used to read the error output of the application. - A that can be used to read the standard error stream of the application. - - writes text to its standard error stream, that text is normally 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] -> To use , you must set to `false`, and you must 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. + Gets a stream used to read the error output of the application. + A that can be used to read the standard error stream of the application. + + stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on 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 on 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 on each other to complete an operation, and neither can proceed. 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-csharp[Executable launched by Process.Start](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/write500lines.cs)] -[!code-vb[Executable launched by Process.Start](~/samples/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. - -[!code-csharp[Reading from the error stream](~/samples/snippets/csharp/api/system.diagnostics/process/standarderror/stderror-sync.cs)] -[!code-vb[Reading from the error stream](~/samples/snippets/visualbasic/api/system.diagnostics/process/standarderror/stderror-sync.vb)] +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/StandardError.md)] -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-csharp[Reading from both streams](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/stdoutput-async.cs)] -[!code-vb[Reading from both streams](~/samples/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. - -> [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. - - - -## 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-cpp[Process_StandardError#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process_StandardError/CPP/source.cpp#1)] - [!code-csharp[Process_StandardError#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process_StandardError/CS/source.cs#1)] - [!code-vb[Process_StandardError#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_StandardError/VB/source.vb#1)] - - ]]> + ]]> The stream has not been defined for redirection; ensure is set to and is set to . @@ -4812,9 +4249,7 @@ You can use asynchronous read operations to avoid these dependencies and their d > [!NOTE] > To use , you must set to `false`, and you must 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 example starts the `sort` command with redirected input. It then prompts the user for text, and passes that to the `sort` process by means of the redirected stream. The `sort` results are displayed to the user on the console. @@ -4885,47 +4320,9 @@ You can use asynchronous read operations to avoid these dependencies and their d writes text to its standard stream, that text is normally displayed on the console. By redirecting 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] -> To use , you must set to `false`, and you must 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 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. - - Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can result in deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits on 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 on 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 on each other to complete an operation, and neither can proceed. 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. +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/StandardOutput.md)] -[!code-csharp[Executable launched by Process.Start](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/write500lines.cs)] -[!code-vb[Executable launched by Process.Start](~/samples/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. - -[!code-csharp[Reading synchronously from a redirected output stream](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/stdoutput-sync.cs)] -[!code-vb[Reading synchronously from a redirected output stream](~/samples/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-csharp[Reading from a redirected output and error stream](~/samples/snippets/csharp/api/system.diagnostics/process/standardoutput/stdoutput-async.cs)] -[!code-vb[Reading from a redirected output and error stream](~/samples/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. - -> [!NOTE] -> You cannot mix asynchronous and synchronous read operations on a redirected stream. Once the redirected stream of a is opened in either asynchronous or synchronous mode, all further read operations on that stream must be in the same mode. For example, do not follow with a call to on the stream, or vice versa. However, you can read two different streams in different modes. For example, you can call and then call for the stream. - - - -## Examples - The following example runs the ipconfig.exe command and redirects its standard output to the example's console window. - - [!code-cpp[Process_StandardOutput#2](~/samples/snippets/cpp/VS_Snippets_CLR/Process_StandardOutput/CPP/process_standardoutput.cpp)] - [!code-csharp[Process_StandardOutput#2](~/samples/snippets/csharp/VS_Snippets_CLR/Process_StandardOutput/CS/process_standardoutput.cs)] - [!code-vb[Process_StandardOutput#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_StandardOutput/VB/process_standardoutput.vb)] - - ]]> + ]]> The stream has not been defined for redirection; ensure is set to and is set to . @@ -4984,43 +4381,11 @@ There is a similar issue when you read all text from both the standard output an if a process resource is started; if no new process resource is started (for example, if an existing process is reused). - component. The return value `true` indicates that a new process resource was started. If the process resource specified by the member of the property is already running on the computer, no additional process resource is started. Instead, the running process resource is reused and `false` is returned. - - You can start a ClickOnce application by specifying 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 drive. - -> [!NOTE] -> If you are using Visual Studio, this overload of the method is the one that you insert into your code after you drag a component onto the designer. Use the `Properties` window to expand the `StartInfo` category and write the appropriate value into the `FileName` property. Your changes will appear in the form's `InitializeComponent` procedure. - - This overload of is not a `static` method. You must call it from an instance of the class. Before calling , you must first specify property information for this instance, because that information is used to determine the process resource to start. - - The other overloads of the method are `static` members. You do not need to create an instance of the component before you call those overloads of the method. Instead, you can call for the class itself, and a new component is created if the process was started. Or, `null` is returned if a process was reused. The process resource is automatically associated with the new component that is returned by the method. - - The members can be used to duplicate the functionality of the `Run` dialog box of the Windows `Start` menu. Anything that can be typed into a command line can be started by setting the appropriate values in the property. The only property that must be set is the property. The property does not have to be an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. - - In the command line, you can specify actions to take for certain types of files. For example, you can print documents or edit text files. Specify these actions using the member of the property. For other types of files, you can specify command-line arguments when you start the file from the `Run` dialog box. For example, you can pass a URL as an argument if you specify your browser as the . These arguments can be specified in the property's member. - - If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - -> [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. - - - -## Examples - The following example uses an instance of the class to start a process. - - [!code-cpp[Process.Start_instance#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp#1)] - [!code-csharp[Process.Start_instance#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_instance/CS/processstart.cs#1)] - [!code-vb[Process.Start_instance#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb#1)] - - ]]> + No file name was specified in the component's . @@ -5077,45 +4442,11 @@ The member Starts the process resource that is specified by the parameter containing process start information (for example, the file name of the process to start) and associates the resource with a new component. A new that is associated with the process resource, or if no process resource is started. Note that a new process that's started alongside already running instances of the same process will be independent from the others. In addition, Start may return a non-null Process with its property already set to . In this case, the started process may have activated an existing instance of itself and then exited. - instance. The overload associates the resource with a new object. - -> [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. - - This overload lets you start a process without first creating a new instance. Using this overload with a parameter is an alternative to the explicit steps of creating a new instance, setting its properties, and calling for the instance. - - Using a instance as the parameter lets you call with the most control over what is passed into the call to start the process. If you need to pass only a file name or a file name and arguments, it is not necessary to create a new instance, although that is an option. The only property that must be set is the property. The property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application that is installed on the system. For example, the property can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc extension if you have associated .doc files with a word processing tool, such as Microsoft Word. - - You can start a ClickOnce application by specifying 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 drive. - - If the and properties of the instance are set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . If the property is `null`, the property must be in UPN format, *user*@*DNS_domain_name*. - - Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the start information for the process resource by using a instance. - - If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - -> [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - - A note about apartment states in managed threads is necessary here. When is `true` on the `startInfo` parameter, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. - - - -## Examples - The following example first spawns an instance of Internet Explorer and displays the contents of the Favorites folder in the browser. It then starts some other instances of Internet Explorer and displays some specific pages or sites. Finally it starts Internet Explorer with the window being minimized while navigating to a specific site. - - For additional examples of other uses of this method, refer to the individual properties of the class. - - [!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] - [!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] - [!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] - - ]]> + No file name was specified in the parameter's property. @@ -5184,43 +4515,11 @@ The member Starts a process resource by specifying the name of a document or application file and associates the resource with a new component. A new that is associated with the process resource, or if no process resource is started. Note that a new process that's started alongside already running instances of the same process will be independent from the others. In addition, Start may return a non-null Process with its property already set to . In this case, the started process may have activated an existing instance of itself and then exited. - object. - -> [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. - - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the member of the property, and calling for the instance. - - You can start a ClickOnce application by setting the `fileName` parameter 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 drive. - - Starting a process by specifying its file name is similar to typing the information in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". - - This overload does not allow command-line arguments for the process. If you need to specify one or more command-line arguments for the process, use the or overloads. - - Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start. - - If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - -> [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. - - - -## Examples - The following example first spawns an instance of Internet Explorer and displays the contents of the Favorites folder in the browser. It then starts some other instances of Internet Explorer and displays some specific pages or sites. Finally it starts Internet Explorer with the window being minimized while navigating to a specific site. - - [!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] - [!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] - [!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] - - ]]> + An error occurred when opening the associated file. @@ -5306,39 +4605,11 @@ The file specified in the could not be found.Starts a process resource by specifying the name of an application and a set of command-line arguments, and associates the resource with a new component. A new that is associated with the process resource, or if no process resource is started. Note that a new process that's started alongside already running instances of the same process will be independent from the others. In addition, Start may return a non-null Process with its property already set to . In this case, the started process may have activated an existing instance of itself and then exited. - object. - -> [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. - - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the and members of the property, and calling for the instance. - - Starting a process by specifying its file name and arguments is similar to typing the file name and command-line arguments in the `Run` dialog box of the Windows `Start` menu. Therefore, the file name does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the file name can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the `Run` dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. If the `fileName` parameter represents a command (.cmd) file, the `arguments` parameter must include either a "`/c`" or "`/k`" argument to specify whether the command window exits or remains after completion. - - Unlike the other overloads, the overload of that has no parameters is not a `static` member. Use that overload when you have already created a instance and specified start information (including the file name), and you want to start a process resource and associate it with the existing instance. Use one of the `static` overloads when you want to create a new component rather than start a process for an existing component. Both this overload and the overload that has no parameters allow you to specify the file name of the process resource to start and command-line arguments to pass. - - If you have a path variable declared in your system using quotes, you must fully qualify that path when starting any process found in that location. Otherwise, the system will not find the path. For example, if `c:\mypath` is not in your path, and you add it using quotation marks: `path = %path%;"c:\mypath"`, you must fully qualify any process in `c:\mypath` when starting it. - -> [!NOTE] -> ASP.NET Web page and server control code executes in the context of the ASP.NET worker process on the Web server. If you use the method in an ASP.NET Web page or server control, the new process executes on the Web server with restricted permissions. The process does not start in the same context as the client browser, and does not have access to the user desktop. - - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - - A note about apartment states in managed threads is necessary here. When is `true` on the process component's property, make sure you have set a threading model on your application by setting the attribute `[STAThread]` on the `main()` method. Otherwise, a managed thread can be in an `unknown` state or put in the `MTA` state, the latter of which conflicts with being `true`. Some methods require that the apartment state not be `unknown`. If the state is not explicitly set, when the application encounters such a method, it defaults to `MTA`, and once set, the apartment state cannot be changed. However, `MTA` causes an exception to be thrown when the operating system shell is managing the thread. - - - -## Examples - The following example first spawns an instance of Internet Explorer and displays the contents of the Favorites folder in the browser. It then starts some other instances of Internet Explorer and displays some specific pages or sites. Finally it starts Internet Explorer with the window being minimized while navigating to a specific site. - - [!code-cpp[Process.Start_static#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_static/CPP/processstartstatic.cpp)] - [!code-csharp[Process.Start_static#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_static/CS/processstartstatic.cs)] - [!code-vb[Process.Start_static#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_static/VB/processstartstatic.vb)] - - ]]> + The or parameter is . An error occurred when opening the associated file. @@ -5413,35 +4684,11 @@ The file specified in the could not be found. Starts a process resource by specifying the name of an application, a user name, a password, and a domain and associates the resource with a new component. A new that is associated with the process resource, or if no process resource is started. Note that a new process that's started alongside already running instances of the same process will be independent from the others. In addition, Start may return a non-null Process with its property already set to . In this case, the started process may have activated an existing instance of itself and then exited. - [!NOTE] -> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. - -> [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. - - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , and properties of the property, and calling for the instance. - - Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. - -> [!NOTE] -> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. - - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - - - -## Examples - The following code example shows the use of this overload to start an executable file and also demonstrates the throwing of a when an attempt is made to start an application associated with a nonexecutable file. - - [!code-csharp[System.Diagnostics.Process.Start#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.Diagnostics.Process.Start/CS/program.cs#1)] - [!code-vb[System.Diagnostics.Process.Start#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Diagnostics.Process.Start/VB/program.vb#1)] - - ]]> + No file name was specified. There was an error in opening the associated file. @@ -5509,27 +4756,11 @@ The file specified in the could not be found.Starts a process resource by specifying the name of an application, a set of command-line arguments, a user name, a password, and a domain and associates the resource with a new component. A new that is associated with the process resource, or if no process resource is started. Note that a new process that's started alongside already running instances of the same process will be independent from the others. In addition, Start may return a non-null Process with its property already set to . In this case, the started process may have activated an existing instance of itself and then exited. - [!NOTE] -> When the executable file is located on a remote drive, you must identify the network share by using a uniform resource identifier (URI), not a linked drive letter. - -> [!NOTE] -> If the address of the executable file to start is a URL, the process is not started and `null` is returned. - - This overload lets you start a process without first creating a new instance. The overload is an alternative to the explicit steps of creating a new instance, setting the , , , , and properties of the property, and calling for the instance. - - Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the `fileName` parameter. For example, you can set the `fileName` parameter to either "Notepad.exe" or "Notepad". If the `fileName` parameter represents an executable file, the `arguments` parameter might represent a file to act upon, such as the text file in `Notepad.exe myfile.txt`. - -> [!NOTE] -> The file name must represent an executable file in the overloads that have `userName`, `password`, and `domain` parameters. - - Whenever you use to start a process, you might need to close it or you risk losing system resources. Close processes using or . You can check whether a process has already been closed by using its property. - - ]]> + No file name was specified. An error occurred when opening the associated file. @@ -5598,29 +4829,11 @@ The file specified in the could not be found. Gets or sets the properties to pass to the method of the . The that represents the data with which to start the process. These arguments include the name of the executable file or document used to start the process. - represents the set of parameters to use to start a process. When is called, the is used to specify the process to start. The only necessary member to set is the property. Starting a process by specifying the property is similar to typing the information in the **Run** dialog box of the Windows **Start** menu. Therefore, the property does not need to represent an executable file. It can be of any file type for which the extension has been associated with an application installed on the system. For example the can have a .txt extension if you have associated text files with an editor, such as Notepad, or it can have a .doc if you have associated .doc files with a word processing tool, such as Microsoft Word. Similarly, in the same way that the **Run** dialog box can accept an executable file name with or without the .exe extension, the .exe extension is optional in the member. For example, you can set the property to either "Notepad.exe" or "Notepad". - - 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 drive. - - If the file name involves a nonexecutable file, such as a .doc file, you can include a verb specifying what action to take on the file. For example, you could set the to "Print" for a file ending in the .doc extension. The file name specified in the property does not need to have an extension if you manually enter a value for the property. However, if you use the property to determine what verbs are available, you must include the extension. - - You can change the parameters specified in the property up to the time that you call the method on the process. After you start the process, changing the values does not affect or restart the associated process. If you call the method with the and properties set, the unmanaged `CreateProcessWithLogonW` function is called, which starts the process in a new window even if the property value is `true` or the property value is . - - You should only access the property on a object returned by the method. For example, you should not access the property on a object returned by . Otherwise, on .NET Core the property will throw an and on .NET Framework it will return a dummy object. - - When the process is started, the file name is the file that populates the (read-only) property. If you want to retrieve the executable file that is associated with the process after the process has started, use the property. If you want to set the executable file of a instance for which an associated process has not been started, use the property's member. Because the members of the property are arguments that are passed to the method of a process, changing the property after the associated process has started will not reset the property. These properties are used only to initialize the associated process. - -## Examples - The following example populates a with the file to execute, the action performed on it and whether it should displays a user interface. For additional examples, refer to the reference pages for properties of the class. - - [!code-cpp[Process.Start_instance#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process.Start_instance/CPP/processstart.cpp#1)] - [!code-csharp[Process.Start_instance#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process.Start_instance/CS/processstart.cs#1)] - [!code-vb[Process.Start_instance#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process.Start_instance/VB/processstart.vb#1)] - - ]]> + The value that specifies the is . .NET 5+ and .NET Core only: The method was not used to start the process. @@ -5744,28 +4957,10 @@ The file specified in the could not be found. The used to marshal event handler calls that are issued as a result of an event on the process. is `null`, methods that handle the event are called on a thread from the system thread pool. For more information about system thread pools, see . - - When the event is handled by a visual Windows Forms component, such as a , accessing the component through the system thread pool might not work, or might result in an exception. Avoid this by setting to a Windows Forms component, which causes the methods handling the event to be called on the same thread on which the component was created. - - If the is used inside Visual Studio 2005 in a Windows Forms designer, is automatically set to the control that contains the . For example, if you place a on a designer for `Form1` (which inherits from ) the property of is set to the instance of `Form1`: - - [!code-cpp[Process_SynchronizingObject#2](~/samples/snippets/cpp/VS_Snippets_CLR/Process_SynchronizingObject/CPP/remarks.cpp#2)] - [!code-csharp[Process_SynchronizingObject#2](~/samples/snippets/csharp/VS_Snippets_CLR/Process_SynchronizingObject/CS/remarks.cs#2)] - [!code-vb[Process_SynchronizingObject#2](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_SynchronizingObject/VB/remarks.vb#2)] - - Typically, this property is set when the component is placed inside a control or form, because those components are bound to a specific thread. - - - -## Examples - [!code-cpp[Process_SynchronizingObject#1](~/samples/snippets/cpp/VS_Snippets_CLR/Process_SynchronizingObject/CPP/process_synchronizingobject.cpp#1)] - [!code-csharp[Process_SynchronizingObject#1](~/samples/snippets/csharp/VS_Snippets_CLR/Process_SynchronizingObject/CS/process_synchronizingobject.cs#1)] - [!code-vb[Process_SynchronizingObject#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/Process_SynchronizingObject/VB/process_synchronizingobject.vb#1)] - - ]]> + +[!INCLUDE[remarks](~/includes/remarks/System.Diagnostics/Process/SynchronizingObject.md)] + + ]]> @@ -6149,9 +5344,7 @@ The file specified in the could not be found. The operating system maps the virtual address space for each process either to pages loaded in physical memory, or to pages stored in the virtual memory paging file on disk. This property can be used to monitor memory usage on computers with 32-bit processors or 64-bit processors. The property value is equivalent to the **Virtual Bytes** performance counter for the process. - - - + ## Examples The following code example starts an instance of the Notepad application. The example then retrieves and displays various properties of the associated process. The example detects when the process exits, and displays its exit code and peak memory statistics. @@ -6211,28 +5404,11 @@ The file specified in the could not be found. Instructs the component to wait indefinitely for the associated process to exit. - makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. - - This method instructs the component to wait an infinite amount of time for the process and event handlers to exit. This can cause an application to stop responding. For example, if you call for a process that has a user interface, the request to the operating system to terminate the associated process might not be handled if the process is written to never enter its message loop. - -> [!NOTE] -> In the .NET Framework 3.5 and earlier versions, the overload waited for milliseconds (approximately 24 days), not indefinitely. Also, previous versions did not wait for the event handlers to exit if the full time was reached. - - This overload ensures that all processing has been completed, including the handling of asynchronous events for redirected standard output. You should use this overload after a call to the overload when standard output has been redirected to asynchronous event handlers. - - When an associated process exits (that is, when it is shut down by the operation system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. - - Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. - - - -## Examples - See the Remarks section of the property reference page. - - ]]> + The wait setting could not be accessed. No process has been set, and a from which the property can be determined does not exist. @@ -6293,28 +5469,11 @@ The file specified in the could not be found. if the associated process has exited; otherwise, . - makes the current thread wait until the associated process terminates. It should be called after all other methods are called on the process. To avoid blocking the current thread, use the event. - - This method instructs the component to wait a finite amount of time for the process to exit. If the associated process does not exit by the end of the interval because the request to terminate is denied, `false` is returned to the calling procedure. You can specify for `milliseconds`, and will behave the same as the overload. If you pass 0 (zero) to the method, it returns `true` only if the process has already exited; otherwise, it immediately returns `false`. - -> [!NOTE] -> In the .NET Framework 3.5 and earlier versions, if `milliseconds` was -1, the overload waited for milliseconds (approximately 24 days), not indefinitely. - - When standard output has been redirected to asynchronous event handlers, it is possible that output processing will not have completed when this method returns. To ensure that asynchronous event handling has been completed, call the overload that takes no parameter after receiving a `true` from this overload. To help ensure that the event is handled correctly in Windows Forms applications, set the property. - - When an associated process exits (is shut down by the operating system through a normal or abnormal termination), the system stores administrative information about the process and returns to the component that had called . The component can then access the information, which includes the , by using the to the exited process. - - Because the associated process has exited, the property of the component no longer points to an existing process resource. Instead, the handle can be used only to access the operating system's information about the process resource. The system is aware of handles to exited processes that have not been released by components, so it keeps the and information in memory until the component specifically frees the resources. For this reason, any time you call for a instance, call when the associated process has terminated and you no longer need any administrative information about it. frees the memory allocated to the exited process. - - - -## Examples - See the code example for the property. - - ]]> + The wait setting could not be accessed. No process has been set, and a from which the property can be determined does not exist. @@ -6589,10 +5748,8 @@ Calling this method will set