diff --git a/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Unix.cs b/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Unix.cs index 5b66e92e708ba..9937c7cdd4071 100644 --- a/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Unix.cs +++ b/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Unix.cs @@ -37,6 +37,9 @@ internal SafeProcessHandle(int processId, SafeWaitHandle handle) : internal int ProcessId { get; } + /// Closes the handle. + /// On Windows, returns if the handle is closed successfully; otherwise. On Unix, always returns + /// On Windows, to get extended error information, call . protected override bool ReleaseHandle() { if (_releaseRef) diff --git a/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Windows.cs b/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Windows.cs index 1fc7a40971327..d822adb9d3792 100644 --- a/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Windows.cs +++ b/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.Windows.cs @@ -16,8 +16,12 @@ namespace Microsoft.Win32.SafeHandles { + /// Provides a managed wrapper for a process handle. public sealed partial class SafeProcessHandle : SafeHandleZeroOrMinusOneIsInvalid { + /// Closes the handle. + /// On Windows, returns if the handle is closed successfully; otherwise. On Unix, always returns + /// On Windows, to get extended error information, call . protected override bool ReleaseHandle() { return Interop.Kernel32.CloseHandle(handle); diff --git a/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.cs b/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.cs index 0175956501d9a..f1b2a9f654d19 100644 --- a/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.cs +++ b/src/libraries/System.Diagnostics.Process/src/Microsoft/Win32/SafeHandles/SafeProcessHandle.cs @@ -15,6 +15,7 @@ namespace Microsoft.Win32.SafeHandles { + /// Provides a managed wrapper for a process handle. public sealed partial class SafeProcessHandle : SafeHandleZeroOrMinusOneIsInvalid { internal static readonly SafeProcessHandle InvalidHandle = new SafeProcessHandle(); @@ -29,6 +30,13 @@ internal SafeProcessHandle(IntPtr handle) { } + /// Initializes a new instance of the class from the specified handle, indicating whether to release the handle during the finalization phase. + /// The handle to be wrapped. + /// to reliably let release the handle during the finalization phase; otherwise, . + /// [!IMPORTANT] + /// > 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`/`catch` 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. + /// ]]> public SafeProcessHandle(IntPtr existingHandle, bool ownsHandle) : base(ownsHandle) { diff --git a/src/libraries/System.Diagnostics.Process/src/System.Diagnostics.Process.csproj b/src/libraries/System.Diagnostics.Process/src/System.Diagnostics.Process.csproj index 2d0ea9a7ba3ee..f5c3ce17998af 100644 --- a/src/libraries/System.Diagnostics.Process/src/System.Diagnostics.Process.csproj +++ b/src/libraries/System.Diagnostics.Process/src/System.Diagnostics.Process.csproj @@ -4,6 +4,7 @@ true $(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-FreeBSD;$(NetCoreAppCurrent)-Linux;$(NetCoreAppCurrent);$(NetCoreAppCurrent)-OSX;$(NetCoreAppCurrent)-MacCatalyst;$(NetCoreAppCurrent)-iOS;$(NetCoreAppCurrent)-tvOS enable + true $(NoWarn);0649 @@ -146,7 +147,7 @@ + Link="Common\Interop\Windows\kernel32\Interop.DuplicateHandle_SafeFileHandle.cs" /> Represents the method that will handle the event or event of a . + /// The source of the event. + /// A that contains the event data. + /// + /// + /// + /// + /// public delegate void DataReceivedEventHandler(object sender, DataReceivedEventArgs e); + /// Provides data for the and events. + /// + /// + /// + /// + /// public class DataReceivedEventArgs : EventArgs { private readonly string? _data; @@ -14,6 +32,11 @@ internal DataReceivedEventArgs(string? data) _data = data; } + /// 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. + /// public string? Data { get { return _data; } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/MonitoringDescriptionAttribute.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/MonitoringDescriptionAttribute.cs index 8ab9c0007edbc..beec1dfc899f6 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/MonitoringDescriptionAttribute.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/MonitoringDescriptionAttribute.cs @@ -6,26 +6,27 @@ namespace System.Diagnostics { - /// - /// DescriptionAttribute marks a property, event, or extender with a - /// description. Visual designers can display this description when referencing - /// the member. - /// + /// Specifies a description for a property or event. + /// A visual designer can display the description when referencing the component member, such as in a Properties window. Access the property to get or set the text associated with this attribute. + /// + /// + /// [AttributeUsage(AttributeTargets.All)] public class MonitoringDescriptionAttribute : DescriptionAttribute { private bool _replaced; - /// - /// Constructs a new sys description. - /// + /// Initializes a new instance of the class, using the specified description. + /// The application-defined description text. + /// The description you specify in the constructor is displayed by a visual designer when you access the property, event, or extender to which the attribute applies + /// public MonitoringDescriptionAttribute(string description) : base(description) { } - /// - /// Retrieves the description text. - /// + /// Gets description text associated with the item monitored. + /// An application-defined description. + /// public override string Description { get diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.NonUap.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.NonUap.cs index be09b7bb146ef..b2339f7f3c86b 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.NonUap.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.NonUap.cs @@ -6,8 +6,34 @@ namespace System.Diagnostics { + /// Provides access to local and remote processes and enables you to start and stop local system processes. + /// + /// + /// + /// + /// + /// + /// Using the .NET Process Class public partial class Process : IDisposable { + /// Immediately stops the associated process, and optionally its child/descendent processes. + /// to kill the associated process and its descendants; to kill only the associated process. + /// When is set to , processes where the call lacks permissions to view details are silently skipped by the descendant termination process because the termination process is unable to determine whether those processes are descendants. + /// The associated process could not be terminated. + /// -or- + /// The process is terminating. + /// You are attempting to call for a process that is running on a remote computer. The method is available only for processes running on the local computer. + /// The process has already exited. + /// -or- + /// There is no process associated with this object. + /// -or- + /// The calling process is a member of the associated process' descendant tree. + /// Not all processes in the associated process' descendant tree could be terminated. + /// + /// + /// public void Kill(bool entireProcessTree) { if (!entireProcessTree) diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Win32.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Win32.cs index f5e4aa38e51f1..272799faa7d5d 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Win32.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Win32.cs @@ -10,6 +10,16 @@ namespace System.Diagnostics { + /// Provides access to local and remote processes and enables you to start and stop local system processes. + /// + /// + /// + /// + /// + /// + /// Using the .NET Process Class public partial class Process : IDisposable { private bool _haveMainWindow; @@ -226,6 +236,16 @@ private string GetMainWindowTitle() return title.Slice(0, length).ToString(); } + /// Gets the window handle of the main window of the associated process. + /// The system-generated window handle of the main window of the associated process. + /// The main window is the window opened by the process that currently has the focus (the form). You must use the method to refresh the object to get the most up to date main window handle if it has changed. In general, because the window handle is cached, use beforehand to guarantee that you'll retrieve the current handle. + /// You can get the property only for processes that are running on the local computer. The property is a value that uniquely identifies the window that is associated with the process. + /// A process has a main window associated with it only if the process has a graphical interface. If the associated process does not have a main window, the value is zero. The value is also zero for processes that have been hidden, that is, processes that are not visible in the taskbar. This can be the case for processes that appear as icons in the notification area, at the far right of the taskbar. + /// If you have just started a process and want to use its main window handle, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, an exception will be thrown. + /// The is not defined because the process has exited. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// public IntPtr MainWindowHandle { get @@ -263,6 +283,22 @@ private bool CloseMainWindowCore() return true; } + /// Gets the caption of the main window of the process. + /// The main window title of the process. + /// A process has a main window associated with it only if the process has a graphical interface. If the associated process does not have a main window (so that is zero), or if the system can't determine that there's a main window (such as may be the case on some Unix platforms), is an empty string (""). + /// If you have just started a process and want to use its main window title, consider using the method to allow the process to finish starting, ensuring that the main window handle has been created. Otherwise, the system throws an exception. + /// [!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. + /// ]]> + /// The following example starts an instance of Notepad and retrieves the caption of the main window of the process. + /// + /// The property is not defined because the process has exited. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. public string MainWindowTitle { get @@ -291,6 +327,20 @@ private bool IsRespondingCore() return Interop.User32.SendMessageTimeout(mainWindow, WM_NULL, IntPtr.Zero, IntPtr.Zero, SMTO_ABORTIFHUNG, 5000, out result) != (IntPtr)0; } + /// Gets a value indicating whether the user interface of the process is responding. + /// if the user interface of the associated process is responding to the system; otherwise, . + /// The value returned by this property represents the most recently refreshed status. To get the most up to date status, you need to call method first. + /// If a process has a user interface, the 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 . 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 . + /// 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. + /// + /// There is no process associated with this object. + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// public bool Responding { get diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Windows.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Windows.cs index f8da13f762a9d..068230850432b 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Windows.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.Windows.cs @@ -13,14 +13,39 @@ namespace System.Diagnostics { + /// Provides access to local and remote processes and enables you to start and stop local system processes. + /// + /// + /// + /// + /// + /// + /// Using the .NET Process Class public partial class Process : IDisposable { private static readonly object s_createProcessLock = new object(); - /// - /// Creates an array of components that are associated with process resources on a - /// remote computer. These process resources share the specified process name. - /// + /// Creates an array of new components and associates them with all the process resources on a remote computer that share the specified process name. + /// The friendly name of the process. + /// The name of a computer on the network. + /// An array of type that represents the process resources running the specified application or file. + /// + /// The parameter syntax is invalid. It might have length zero (0). + /// The parameter is . + /// The operating system platform does not support this operation on remote computers. + /// The attempt to connect to has failed. + /// -or- + /// 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. + /// A problem occurred accessing an underlying system API. + /// + /// + /// + /// + /// public static Process[] GetProcessesByName(string? processName, string machineName) { if (processName == null) @@ -46,6 +71,21 @@ public static Process[] GetProcessesByName(string? processName, string machineNa return list.ToArray(); } + /// 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. + /// The name of an application file to run in the process. + /// The user name to use when starting the process. + /// A that contains the password to use when starting the process. + /// The domain to use when starting the process. + /// 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. + /// + /// No file name was specified. + /// There was an error in opening the associated file. + /// -or- + /// The file specified in the could not be found. + /// The process object has already been disposed. + /// This member is not supported on Linux or macOS (.NET Core only). [CLSCompliant(false)] [SupportedOSPlatform("windows")] public static Process? Start(string fileName, string userName, SecureString password, string domain) @@ -58,6 +98,24 @@ public static Process[] GetProcessesByName(string? processName, string machineNa return Start(startInfo); } + /// 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. + /// The name of an application file to run in the process. + /// Command-line arguments to pass when starting the process. + /// The user name to use when starting the process. + /// A that contains the password to use when starting the process. + /// The domain to use when starting the process. + /// 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. + /// + /// No file name was specified. + /// An error occurred when opening the associated file. + /// -or- + /// The file specified in the could not be found. + /// -or- + /// The sum of the length of the arguments and the length of the full path to the associated file exceeds 2080. The error message associated with this exception can be one of the following: "The data area passed to a system call is too small." or "Access is denied." + /// The process object has already been disposed. + /// This member is not supported on Linux or macOS (.NET Core only). [CLSCompliant(false)] [SupportedOSPlatform("windows")] public static Process? Start(string fileName, string arguments, string userName, SecureString password, string domain) @@ -70,25 +128,29 @@ public static Process[] GetProcessesByName(string? processName, string machineNa return Start(startInfo); } - /// - /// Puts a Process component in state to interact with operating system processes that run in a - /// special mode by enabling the native property SeDebugPrivilege on the current thread. - /// + /// Puts a component in state to interact with operating system processes that run in a special mode by enabling the native property on the current thread. + /// Some operating system processes run in a special mode. Attempting to read properties of or attach to these processes is not possible unless you have called on the component. Call when you no longer need access to these processes that run in special mode. + /// public static void EnterDebugMode() { SetPrivilege(Interop.Advapi32.SeDebugPrivilege, (int)Interop.Advapi32.SEPrivileges.SE_PRIVILEGE_ENABLED); } - /// - /// Takes a Process component out of the state that lets it interact with operating system processes - /// that run in a special mode. - /// + /// Takes a component out of the state that lets it interact with operating system processes that run in a special mode. + /// Some operating system processes run in a special mode. Attempting to read properties of or attach to these processes is not possible unless you have called on the component. Call when you no longer need access to these processes that run in special mode. + /// public static void LeaveDebugMode() { SetPrivilege(Interop.Advapi32.SeDebugPrivilege, 0); } - /// Terminates the associated process immediately. + /// Immediately stops the associated process. + /// The associated process could not be terminated. + /// You are attempting to call for a process that is running on a remote computer. The method is available only for processes running on the local computer. + /// There is no process associated with this object. + /// + /// + /// public void Kill() { using (SafeProcessHandle handle = GetProcessHandle(Interop.Advapi32.ProcessOptions.PROCESS_TERMINATE | Interop.Advapi32.ProcessOptions.PROCESS_QUERY_LIMITED_INFORMATION, throwIfExited: false)) @@ -190,6 +252,14 @@ private bool WaitForExitCore(int milliseconds) } /// Gets the main module for the associated process. + /// The that was used to start the process. + /// A process module represents a.dll or .exe file that is loaded into a particular process. The property lets you view information about the executable used to start the process, including the module name, file name, and module memory details. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// A 32-bit process is trying to access the modules of a 64-bit process. + /// The process is not available. + /// -or- + /// The process has exited. + /// public ProcessModule? MainModule { get @@ -260,7 +330,18 @@ private DateTime ExitTimeCore get { return GetProcessTimes().ExitTime; } } - /// Gets the amount of time the process has spent running code inside the operating system core. + /// Gets the privileged processor time for this process. + /// A that indicates the amount of time that the process has spent running code inside the operating system core. + /// + /// 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. + /// + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// public TimeSpan PrivilegedProcessorTime { get { return GetProcessTimes().PrivilegedProcessorTime; } @@ -272,20 +353,35 @@ internal DateTime StartTimeCore get { return GetProcessTimes().StartTime; } } - /// - /// Gets the amount of time the associated process has spent utilizing the CPU. - /// It is the sum of the and - /// . - /// + /// Gets the total processor time for this process. + /// A that indicates the amount of time that the associated process has spent utilizing the CPU. This value is the sum of the and the . + /// + /// 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. + /// + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// public TimeSpan TotalProcessorTime { get { return GetProcessTimes().TotalProcessorTime; } } - /// - /// Gets the amount of time the associated process has spent running code - /// inside the application portion of the process (not the operating system core). - /// + /// Gets the user processor time for this process. + /// A that indicates the amount of time that the associated process has spent running code inside the application portion of the process (not inside the operating system core). + /// + /// 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. + /// + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// public TimeSpan UserProcessorTime { get { return GetProcessTimes().UserProcessorTime; } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.cs index 9789c2baddb68..406f3bee20330 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/Process.cs @@ -15,12 +15,16 @@ namespace System.Diagnostics { - /// - /// - /// Provides access to local and remote - /// processes. Enables you to start and stop system processes. - /// - /// + /// Provides access to local and remote processes and enables you to start and stop local system processes. + /// + /// + /// + /// + /// + /// + /// Using the .NET Process Class [Designer("System.Diagnostics.Design.ProcessDesigner, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] public partial class Process : Component { @@ -73,8 +77,25 @@ public partial class Process : Component private StreamReadMode _outputStreamReadMode; private StreamReadMode _errorStreamReadMode; - // Support for asynchronously reading streams + /// Occurs each time an application writes a line to its redirected stream. + /// + /// + /// + /// + /// + /// public event DataReceivedEventHandler? OutputDataReceived; + /// Occurs when an application writes to its redirected stream. + /// + /// + /// + /// + /// + /// public event DataReceivedEventHandler? ErrorDataReceived; // Abstract the stream details @@ -85,11 +106,10 @@ public partial class Process : Component private static int s_cachedSerializationSwitch; - /// - /// - /// Initializes a new instance of the class. - /// - /// + /// Initializes a new instance of the class. + /// public Process() { // This class once inherited a finalizer. For backward compatibility it has one so that @@ -118,6 +138,9 @@ private Process(string machineName, bool isRemoteMachine, int processId, Process _errorStreamReadMode = StreamReadMode.Undefined; } + /// Gets the native handle to this process. + /// The native handle to this process. + /// The handle is only available if the calling component started the process. public SafeProcessHandle SafeHandle { get @@ -127,6 +150,21 @@ public SafeProcessHandle SafeHandle } } + /// Gets the native handle of the associated process. + /// The handle that the operating system assigned to the associated process when the process was started. The system uses this handle to keep track of process attributes. + /// An application can obtain a handle to a process that can be used as a parameter to many process-information and control functions. You can use this handle to initialize a or to call native methods with platform invoke. + /// This process handle is private to an application--in other words, process handles cannot be shared. A process also has a process which, unlike the , is unique and, therefore, valid throughout the system. + /// Only processes started through a call to set the property of the corresponding instances. + /// The process has not been started or has exited. The property cannot be read because there is no process associated with this instance. + /// -or- + /// The instance has been attached to a running process but you do not have the necessary permissions to get a handle with full access rights. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// + /// + /// + /// + /// public IntPtr Handle => SafeHandle.DangerousGetHandle(); /// @@ -138,12 +176,17 @@ private bool Associated get { return _haveProcessId || _haveProcessHandle; } } - /// - /// - /// Gets the base priority of - /// the associated process. - /// - /// + /// Gets the base priority of the associated process. + /// The base priority, which is computed from the of the associated process. + /// + /// The process has exited. + /// -or- + /// The process has not started, so there is no process ID. + /// + /// + /// public int BasePriority { get @@ -153,13 +196,20 @@ public int BasePriority } } - /// - /// - /// Gets - /// the - /// value that was specified by the associated process when it was terminated. - /// - /// + /// Gets the value that the associated process specified when it terminated. + /// The code that the associated process specified when it terminated. + /// + /// The process has not exited. + /// -or- + /// The process is not valid. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// + /// + /// + /// public int ExitCode { get @@ -169,12 +219,19 @@ public int ExitCode } } - /// - /// - /// Gets a - /// value indicating whether the associated process has been terminated. - /// - /// + /// Gets a value indicating whether the associated process has been terminated. + /// if the operating system process referenced by the component has terminated; otherwise, . + /// + /// There is no process associated with the object. + /// The exit code for the process could not be retrieved. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// + /// + /// + /// public bool HasExited { get @@ -192,7 +249,13 @@ public bool HasExited } } - /// Gets the time the associated process was started. + /// Gets the time that the associated process was started. + /// An object that indicates when the process started. An exception is thrown if the process is not running. + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process has exited. + /// -or- + /// The process has not been started. + /// An error occurred in the call to the Windows function. public DateTime StartTime { get @@ -205,11 +268,17 @@ public DateTime StartTime } } - /// - /// - /// Gets the time that the associated process exited. - /// - /// + /// Gets the time that the associated process exited. + /// A that indicates when the associated process was terminated. + /// If the process has not terminated, attempting to retrieve the property throws an exception. Use before getting the property to determine whether the associated process has terminated. + /// 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. + /// + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// + /// public DateTime ExitTime { get @@ -224,12 +293,16 @@ public DateTime ExitTime } } - /// - /// - /// Gets - /// the unique identifier for the associated process. - /// - /// + /// Gets the unique identifier for the associated process. + /// The system-generated unique identifier of the process that is referenced by this instance. + /// + /// The process's property has not been set. + /// -or- + /// There is no process associated with this object. + /// + /// public int Id { get @@ -239,12 +312,22 @@ public int Id } } - /// - /// - /// Gets - /// the name of the computer on which the associated process is running. - /// - /// + /// Gets the name of the computer the associated process is running on. + /// The name of the computer that the associated process is running on. + /// You can view statistical data and process information for processes running on remote computers but you cannot call , , or on remote computers. + /// [!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. + /// ]]> + /// 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. + /// + /// There is no process associated with this object. + /// + /// + /// public string MachineName { get @@ -254,10 +337,27 @@ public string MachineName } } - /// - /// Gets or sets the maximum allowable working set for the associated process. - /// - /// On macOS and FreeBSD, setting the value works only for the current process. + /// Gets or sets the maximum allowable working set size, in bytes, for the associated process. + /// The maximum working set size that is allowed in memory for the process, in bytes. + /// The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. + /// The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that your application executes, including the pages in your .dll files and the system.dll files. As the working set size increases, memory demand increases. + /// A process has minimum and maximum working set sizes. Each time a process resource is created, the system reserves an amount of memory equal to the minimum working set size for the process. The virtual memory manager attempts to keep at least the minimum amount of memory resident when the process is active, but it never keeps more than the maximum size. + /// The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. + /// [!NOTE] + /// > When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. + /// ]]> + /// The maximum working set size is invalid. It must be greater than or equal to the minimum working set size. + /// Working set information cannot be retrieved from the associated process resource. + /// -or- + /// The process identifier or process handle is zero because the process has not been started. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process is not available. + /// -or- + /// The process has exited. + /// + /// + /// public IntPtr MaxWorkingSet { get @@ -274,10 +374,27 @@ public IntPtr MaxWorkingSet } } - /// - /// Gets or sets the minimum allowable working set for the associated process. - /// - /// On macOS and FreeBSD, setting the value works only for the current process. + /// Gets or sets the minimum allowable working set size, in bytes, for the associated process. + /// The minimum working set size that is required in memory for the process, in bytes. + /// The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. + /// The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that your application executes, including the pages in your .dll files and the system.dll files. As the working set size increases, memory demand increases. + /// A process has minimum and maximum working set sizes. Each time a process resource is created, the system reserves an amount of memory equal to the minimum working set size for the process. The virtual memory manager attempts to keep at least the minimum amount of memory resident when the process is active, but it never keeps more than the maximum size. + /// The system sets the default working set sizes. You can modify these sizes using the and members. However, setting these values does not guarantee that the memory will be reserved or resident. + /// [!NOTE] + /// > When you increase the working set size of a process, you take physical memory away from the rest of the system. Ensure that you do not request a minimum or maximum working set size that is too large, because doing so can degrade system performance. + /// ]]> + /// The minimum working set size is invalid. It must be less than or equal to the maximum working set size. + /// Working set information cannot be retrieved from the associated process resource. + /// -or- + /// The process identifier or process handle is zero because the process has not been started. + /// You are trying to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process is not available. + /// -or- + /// The process has exited. + /// + /// + /// public IntPtr MinWorkingSet { get @@ -294,6 +411,16 @@ public IntPtr MinWorkingSet } } + /// Gets the modules that have been loaded by the associated process. + /// An array of type that represents the modules that have been loaded by the associated process. + /// The value returned by this property represents the most recently refreshed modules. To get the most up to date information, you need to call method first. + /// A process module represents a.dll or .exe file that is loaded into a particular process. A instance lets you view information about a module, including the module name, file name, and module memory details. + /// A process can load multiple modules into memory. For example,.exe files that load additional .dll files have multiple modules. + /// After starting the process, this collection is empty until the system has loaded the process. If the process has a main window, you can call before retrieving this property to ensure that the collection is nonempty when you get the list. + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process is not available. + /// You are attempting to access the property for either the system process or the idle process. These processes do not have modules. + /// public ProcessModuleCollection Modules { get @@ -307,6 +434,18 @@ public ProcessModuleCollection Modules } } + /// Gets the amount of nonpaged system memory, in bytes, allocated for the associated process. + /// The amount of system memory, in bytes, allocated for the associated process that cannot be written to the virtual memory paging file. + /// The value returned by this property represents the most recently refreshed size of nonpaged system memory used by the process, in bytes. To get the most up to date size, you need to call method first. + /// System memory is the physical memory used by the operating system, and is divided into paged and nonpaged pools. Nonpaged memory allocations remain in system memory and are not paged out to the virtual memory paging file. + /// 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 Nonpaged Bytes performance counter for the process. + /// 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. + /// + /// public long NonpagedSystemMemorySize64 { get @@ -316,6 +455,9 @@ public long NonpagedSystemMemorySize64 } } + /// Gets the amount of nonpaged system memory, in bytes, allocated for the associated process. + /// The amount of memory, in bytes, the system has allocated for the associated process that cannot be written to the virtual memory paging file. + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.NonpagedSystemMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int NonpagedSystemMemorySize { @@ -326,7 +468,19 @@ public int NonpagedSystemMemorySize } } - + /// Gets the amount of paged memory, in bytes, allocated for the associated process. + /// The amount of memory, in bytes, allocated in the virtual memory paging file for the associated process. + /// The value returned by this property represents the most recently refreshed size of memory in the virtual memory paging file used by the process, in bytes. To get the most up to date size, you need to call method first. + /// The operating system uses the virtual memory paging file in conjunction with physical memory to manage the virtual address space for each process. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of memory used by the operating system for the process, use the 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. + /// 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. + /// + /// + /// public long PagedMemorySize64 { get @@ -336,6 +490,9 @@ public long PagedMemorySize64 } } + /// Gets the amount of paged memory, in bytes, allocated for the associated process. + /// The amount of memory, in bytes, allocated by the associated process that can be written to the virtual memory paging file. + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.PagedMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int PagedMemorySize { @@ -346,7 +503,18 @@ public int PagedMemorySize } } - + /// Gets the amount of pageable system memory, in bytes, allocated for the associated process. + /// The amount of system memory, in bytes, allocated for the associated process that can be written to the virtual memory paging file. + /// The value returned by this property value represents the current size of pageable system memory used by the process, in bytes. System memory is the physical memory used by the operating system, and is divided into paged and nonpaged pools. When pageable memory is not in use, it can be transferred to the virtual memory paging file on disk. To obtain the size of the application memory used by the process, use the 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. + /// 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. + /// + /// + /// public long PagedSystemMemorySize64 { get @@ -356,6 +524,9 @@ public long PagedSystemMemorySize64 } } + /// Gets the amount of pageable system memory, in bytes, allocated for the associated process. + /// The amount of memory, in bytes, the system has allocated for the associated process that can be written to the virtual memory paging file. + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.PagedSystemMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int PagedSystemMemorySize { @@ -366,7 +537,17 @@ public int PagedSystemMemorySize } } - + /// Gets the maximum amount of memory in the virtual memory paging file, in bytes, used by the associated process. + /// The maximum amount of memory, in bytes, allocated in the virtual memory paging file for the associated process since it was started. + /// The value returned by this property value represents the maximum size of memory in the virtual memory paging file used by the process since it started, in bytes. The operating system uses the virtual memory paging file in conjunction with physical memory to manage the virtual address space for each process. When pageable memory is not in use, it can be transferred to 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 Page File Bytes Peak performance counter for the process. + /// 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. + /// + /// public long PeakPagedMemorySize64 { get @@ -376,6 +557,9 @@ public long PeakPagedMemorySize64 } } + /// Gets the maximum amount of memory in the virtual memory paging file, in bytes, used by the associated process. + /// The maximum amount of memory, in bytes, allocated by the associated process that could be written to the virtual memory paging file. + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.PeakPagedMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int PeakPagedMemorySize { @@ -386,6 +570,20 @@ public int PeakPagedMemorySize } } + /// Gets the maximum amount of physical memory, in bytes, used by the associated process. + /// The maximum amount of physical memory, in bytes, allocated for the associated process since it was started. + /// The value returned by this property represents the maximum size of working set memory used by the process since it started, in bytes. The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. + /// The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that the process executes, including instructions from the process modules and the system libraries. + /// 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 Working Set Peak performance counter for the process. + /// 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. + /// + /// + /// + /// public long PeakWorkingSet64 { get @@ -395,6 +593,14 @@ public long PeakWorkingSet64 } } + /// Gets the peak working set size for the associated process, in bytes. + /// The maximum amount of physical memory that the associated process has required all at once, in bytes. + /// The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. + /// The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that the process executes, including process modules and the system libraries. + /// + /// + /// + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.PeakWorkingSet64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int PeakWorkingSet { @@ -405,6 +611,17 @@ public int PeakWorkingSet } } + /// Gets the maximum amount of virtual memory, in bytes, used by the associated process. + /// The maximum amount of virtual memory, in bytes, allocated for the associated process since it was started. + /// The value returned by this property represents the maximum size of virtual memory used by the process since it started, in bytes. 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 Peak performance counter for the process. + /// 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. + /// + /// public long PeakVirtualMemorySize64 { get @@ -414,6 +631,9 @@ public long PeakVirtualMemorySize64 } } + /// Gets the maximum amount of virtual memory, in bytes, used by the associated process. + /// The maximum amount of virtual memory, in bytes, that the associated process has requested. + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.PeakVirtualMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int PeakVirtualMemorySize { @@ -424,13 +644,20 @@ public int PeakVirtualMemorySize } } - /// - /// - /// Gets or sets a value indicating whether the associated process priority - /// should be temporarily boosted by the operating system when the main window - /// has focus. - /// - /// + /// Gets or sets a value indicating whether the associated process priority should temporarily be boosted by the operating system when the main window has the focus. + /// if dynamic boosting of the process priority should take place for a process when it is taken out of the wait state; otherwise, . The default is . + /// The value returned by this property represents the most recently refreshed temporary priority boost. To get the most up to date value, you need to call method first. + /// When a thread runs in a process for which the priority class has one of the dynamic priority enumeration values (, , or ), the system temporarily boosts the thread's priority when it is taken out of a wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all the existing threads and any threads subsequently created by the process. To restore normal behavior, set the property to . + /// [!NOTE] + /// > Boosting the priority too high can drain resources from essential operating system and network functions, causing problems with other operating system tasks. + /// ]]> + /// Priority boost information could not be retrieved from the associated process resource. + /// The process identifier or process handle is zero. (The process has not been started.) + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process is not available. + /// + /// public bool PriorityBoostEnabled { get @@ -450,12 +677,19 @@ public bool PriorityBoostEnabled } } - /// - /// - /// Gets or sets the overall priority category for the - /// associated process. - /// - /// + /// Gets or sets the overall priority category for the associated process. + /// The priority category for the associated process, from which the of the process is calculated. + /// + /// Process priority information could not be set or retrieved from the associated process resource. + /// -or- + /// The process identifier or process handle is zero. (The process has not been started.) + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process is not available. + /// Priority class cannot be set because it does not use a valid value, as defined in the enumeration. + /// + /// public ProcessPriorityClass PriorityClass { get @@ -480,6 +714,16 @@ public ProcessPriorityClass PriorityClass } } + /// Gets the amount of private memory, in bytes, allocated for the associated process. + /// The amount of memory, in bytes, allocated for the associated process that cannot be shared with other processes. + /// The value returned by this property represents the most recently refreshed size of memory used by the process, in bytes, that cannot be shared with other processes. To get the most up to date size, you need to call 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. + /// 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. + /// public long PrivateMemorySize64 { get @@ -489,6 +733,9 @@ public long PrivateMemorySize64 } } + /// Gets the amount of private memory, in bytes, allocated for the associated process. + /// The number of bytes allocated by the associated process that cannot be shared with other processes. + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.PrivateMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int PrivateMemorySize { @@ -499,12 +746,19 @@ public int PrivateMemorySize } } - /// - /// - /// Gets - /// the friendly name of the process. - /// - /// + /// Gets the name of the process. + /// The name that the system uses to identify the process to the user. + /// property holds an executable file name, such as Outlook, that does not include the .exe extension or the path. It is helpful for getting and manipulating all the processes that are associated with the same executable file. + /// > [!NOTE] + /// > On [!INCLUDE[Win2kFamily](~/includes/win2kfamily-md.md)] operating systems, the property may be truncated to 15 characters if the process module information cannot be obtained. + /// You can call , passing it an executable file name, to retrieve an array that contains every running instance on the specified computer. You can use this array, for example, to shut down all the running instances of the executable file. + /// ]]> + /// The process does not have an identifier, or no process is associated with the . + /// -or- + /// The associated process has exited. + /// The process is not on this computer. + /// public string ProcessName { get @@ -514,12 +768,18 @@ public string ProcessName } } - /// - /// - /// Gets - /// or sets which processors the threads in this process can be scheduled to run on. - /// - /// + /// 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. + /// + /// information could not be set or retrieved from the associated process resource. + /// -or- + /// The process identifier or process handle is zero. (The process has not been started.) + /// You are attempting to access the property for a process that is running on a remote computer. This property is available only for processes that are running on the local computer. + /// The process was not available. + /// -or- + /// The process has exited. public IntPtr ProcessorAffinity { get @@ -539,6 +799,13 @@ public IntPtr ProcessorAffinity } } + /// Gets the Terminal Services session identifier for the associated process. + /// The Terminal Services session identifier for the associated process. + /// The property identifies the session in which the application is currently running. + /// There is no session associated with this process. + /// There is no process associated with this session identifier. + /// -or- + /// The associated process is not on this machine. public int SessionId { get @@ -548,11 +815,15 @@ public int SessionId } } - /// - /// - /// Gets or sets the properties to pass into the method for the . - /// - /// + /// 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. + /// + /// The value that specifies the is . + /// .NET 5+ and .NET Core only: The method was not used to start the process. + /// + /// public ProcessStartInfo StartInfo { get @@ -584,12 +855,16 @@ public ProcessStartInfo StartInfo } } - /// - /// - /// Gets the set of threads that are running in the associated - /// process. - /// - /// + /// Gets the set of threads that are running in the associated process. + /// An array of type representing the operating system threads currently running in the associated process. + /// The value returned by this property represents the most recently refreshed threads. To get the most up to date information, you need to call method first. + /// A thread executes code in a process. Each process is started with a single thread, its primary thread. Any thread can create additional threads. Threads within a process share the address space of the process. + /// Use to get all the threads associated with the current process. The primary thread is not necessarily at index zero in the array. + /// The process does not have an , or no process is associated with the instance. + /// -or- + /// The associated process has exited. + /// + /// public ProcessThreadCollection Threads { get @@ -611,6 +886,14 @@ public ProcessThreadCollection Threads } } + /// Gets the number of handles opened by the process. + /// The number of operating system handles the process has opened. + /// The value returned by this property represents the most recently refreshed handle count. To get the most up to date handle count, you need to call method first. + /// Handles provide a way for a process to refer to objects. A process can obtain handles to files, resources, message queues, and many other operating system objects. The operating system reclaims the memory associated with the process only when the handle count is zero. + /// + /// + /// + /// public int HandleCount { get @@ -623,6 +906,18 @@ public int HandleCount partial void EnsureHandleCountPopulated(); + /// Gets the amount of the virtual memory, in bytes, allocated for the associated process. + /// The amount of virtual memory, in bytes, allocated for the associated process. + /// The value returned by this property represents the most recently refreshed size of virtual memory used by the process, in bytes. To get the most up to date size, you need to call method first. + /// 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. + /// 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. + /// + /// public long VirtualMemorySize64 { get @@ -632,6 +927,10 @@ public long VirtualMemorySize64 } } + /// Gets the size of the process's virtual memory, in bytes. + /// The amount of virtual memory, in bytes, that the associated process has requested. + /// + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.VirtualMemorySize64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int VirtualMemorySize { @@ -642,13 +941,18 @@ public int VirtualMemorySize } } - /// - /// - /// Gets or sets whether the - /// event is fired - /// when the process terminates. - /// - /// + /// Gets or sets whether the event should be raised when the process terminates. + /// 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. + /// + /// + /// + /// + /// + /// + /// + /// public bool EnableRaisingEvents { get @@ -675,10 +979,23 @@ public bool EnableRaisingEvents } } - - /// - /// [To be supplied.] - /// + /// Gets a stream used to write the input of the application. + /// A that can be used to write the standard input stream of the application. + /// A can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. + /// [!NOTE] + /// > To use , you must set to `false`, and you must set to `true`. Otherwise, writing to the stream throws an exception. + /// ]]> + /// 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. + /// + /// The stream has not been defined because is set to . + /// + /// + /// public StreamWriter StandardInput { get @@ -694,9 +1011,17 @@ public StreamWriter StandardInput } } - /// - /// [To be supplied.] - /// + /// Gets a stream used to read the textual output of the application. + /// A that can be used to read the standard output stream of the application. + /// + /// The stream has not been defined for redirection; ensure is set to and is set to . + /// -or- + /// The stream has been opened for asynchronous read operations with . + /// + /// + /// public StreamReader StandardOutput { get @@ -720,9 +1045,17 @@ public StreamReader StandardOutput } } - /// - /// [To be supplied.] - /// + /// 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. + /// + /// The stream has not been defined for redirection; ensure is set to and is set to . + /// -or- + /// The stream has been opened for asynchronous read operations with . + /// + /// + /// public StreamReader StandardError { get @@ -746,6 +1079,21 @@ public StreamReader StandardError } } + /// Gets the amount of physical memory, in bytes, allocated for the associated process. + /// The amount of physical memory, in bytes, allocated for the associated process. + /// The value returned by this property represents the most recently refreshed size of working set memory used by the process, in bytes. To get the most up to date size, you need to call method first. + /// The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. + /// The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that the process executes, including instructions in the process modules and the system libraries. + /// 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 Working Set performance counter for the process. + /// 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. + /// + /// + /// + /// public long WorkingSet64 { get @@ -755,6 +1103,22 @@ public long WorkingSet64 } } + /// Gets the associated process's physical memory usage, in bytes. + /// The total amount of physical memory the associated process is using, in bytes. + /// The value returned by this property represents the most recently refreshed size of working set memory used by the process, in bytes. To get the most up to date size, you need to call method first. + /// The working set of a process is the set of memory pages currently visible to the process in physical RAM memory. These pages are resident and available for an application to use without triggering a page fault. + /// The working set includes both shared and private data. The shared data includes the pages that contain all the instructions that the process executes, including the process modules and the system libraries. + /// 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' exit code. + /// + /// + /// + /// + /// + /// [ObsoleteAttribute("This property has been deprecated because the type of the property can't represent all valid results. Please use System.Diagnostics.Process.WorkingSet64 instead. https://go.microsoft.com/fwlink/?linkid=14202")] public int WorkingSet { @@ -797,12 +1161,8 @@ private void CompletionCallback(object? waitHandleContext, bool wasSignaled) } } - /// - /// - /// - /// Free any resources associated with this component. - /// - /// + /// Release all resources used by this process. + /// to release both managed and unmanaged resources; to release only unmanaged resources. protected override void Dispose(bool disposing) { if (!_disposed) @@ -816,28 +1176,85 @@ protected override void Dispose(bool disposing) } } + /// Closes a process that has a user interface by sending a close message to its main window. + /// if the close message was successfully sent; if the associated process does not have a main window or if the main window is disabled (for example if a modal dialog is being shown). + /// When a process 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 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. + /// 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. + /// 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. + /// + /// The process has already exited. + /// -or- + /// No process is associated with this object. public bool CloseMainWindow() { return CloseMainWindowCore(); } + /// Causes the component to wait indefinitely for the associated process to enter an idle state. This overload applies only to processes with a user interface and, therefore, a message loop. + /// if the associated process has reached an idle state. + /// Use to force the processing of your application to wait until the message loop has returned to the idle state. When a process with a user interface is executing, its message loop executes every time a Windows message is sent to the process by the operating system. The process then returns to the message loop. A process is said to be in an idle state when it is waiting for messages inside of a message loop. This state is useful, for example, when your application needs to wait for a starting process to finish creating its main window before the application communicates with that window. + /// If a process does not have a message loop, throws an . + /// The overload instructs the component to wait indefinitely for the process to become idle in the message loop. This instruction can cause an application to stop responding. For example, if the process is written to always exit its message loop immediately, as in the code fragment `while(true)`. + /// The process does not have a graphical interface. + /// -or- + /// An unknown error occurred. The process failed to enter an idle state. + /// -or- + /// The process has already exited. + /// -or- + /// No process is associated with this object. + /// + /// public bool WaitForInputIdle() { return WaitForInputIdle(int.MaxValue); } + /// Causes the component to wait the specified number of milliseconds for the associated process to enter an idle state. This overload applies only to processes with a user interface and, therefore, a message loop. + /// A value of 1 to that specifies the amount of time, in milliseconds, to wait for the associated process to become idle. A value of 0 specifies an immediate return, and a value of -1 specifies an infinite wait. + /// if the associated process has reached an idle state; otherwise, . + /// Use to force the processing of your application to wait until the message loop has returned to the idle state. When a process with a user interface is executing, its message loop executes every time a Windows message is sent to the process by the operating system. The process then returns to the message loop. A process is said to be in an idle state when it is waiting for messages inside of a message loop. This state is useful, for example, when your application needs to wait for a starting process to finish creating its main window before the application communicates with that window. + /// If a process does not have a message loop, throws an . + /// The overload instructs the component to wait a finite amount of time for the process to become idle in the message loop. If the associated process has not become idle by the end of the interval because the loop is still processing messages, is returned to the calling procedure. + /// For more information about handling events, see [Handling and Raising Events](/dotnet/standard/events/). + /// The process does not have a graphical interface. + /// -or- + /// An unknown error occurred. The process failed to enter an idle state. + /// -or- + /// The process has already exited. + /// -or- + /// No process is associated with this object. + /// + /// public bool WaitForInputIdle(int milliseconds) { return WaitForInputIdleCore(milliseconds); } + /// Gets or sets the object used to marshal the event handler calls that are issued as a result of a process exit event. + /// The used to marshal event handler calls that are issued as a result of an event on the process. + /// + /// public ISynchronizeInvoke? SynchronizingObject { get; set; } - /// - /// - /// Frees any resources associated with this component. - /// - /// + /// Frees all the resources that are associated with this component. + /// The method causes the process to stop waiting for exit if it was waiting, closes the process handle, and clears process-specific properties. does not close the standard output, input, and error readers and writers in case they are being referenced externally. + /// [!NOTE] + /// > The method calls . Placing the object in a `using` block disposes of resources without the need to call . + /// ]]> + /// 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. + /// public void Close() { if (Associated) @@ -998,12 +1415,23 @@ private void SetWorkingSetLimits(IntPtr? min, IntPtr? max) _haveWorkingSetLimits = true; } - /// - /// - /// Returns a new component given a process identifier and - /// the name of a computer in the network. - /// - /// + /// Returns a new component, given a process identifier and the name of a computer on the network. + /// The system-unique identifier of a process resource. + /// The name of a computer on the network. + /// A component that is associated with a remote process resource identified by the parameter. + /// + /// The process specified by the parameter is not running. The identifier might be expired. + /// -or- + /// The parameter syntax is invalid. The name might have length zero (0). + /// The parameter is . + /// The process was not started by this object. + /// + /// + /// + /// + /// public static Process GetProcessById(int processId, string machineName) { if (!ProcessManager.IsProcessRunning(processId, machineName)) @@ -1014,48 +1442,68 @@ public static Process GetProcessById(int processId, string machineName) return new Process(machineName, ProcessManager.IsRemoteMachine(machineName), processId, null); } - /// - /// - /// Returns a new component given the - /// identifier of a process on the local computer. - /// - /// + /// Returns a new component, given the identifier of a process on the local computer. + /// The system-unique identifier of a process resource. + /// A component that is associated with the local process resource identified by the parameter. + /// + /// The process specified by the parameter is not running. The identifier might be expired. + /// The process was not started by this object. + /// + /// + /// + /// public static Process GetProcessById(int processId) { return GetProcessById(processId, "."); } - /// - /// - /// Creates an array of components that are - /// associated - /// with process resources on the - /// local computer. These process resources share the specified process name. - /// - /// + /// Creates an array of new components and associates them with all the process resources on the local computer that share the specified process name. + /// The friendly name of the process. + /// An array of type that represents the process resources running the specified application or file. + /// + /// 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. + /// + /// + /// + /// public static Process[] GetProcessesByName(string? processName) { return GetProcessesByName(processName, "."); } - /// - /// - /// Creates a new - /// component for each process resource on the local computer. - /// - /// + /// 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. + /// + /// + /// + /// + /// public static Process[] GetProcesses() { return GetProcesses("."); } - /// - /// - /// Creates a new - /// component for each - /// process resource on the specified computer. - /// - /// + /// Creates a new component for each process resource on the specified computer. + /// The computer from which to read the list of processes. + /// An array of type that represents all the process resources running on the specified computer. + /// + /// The parameter syntax is invalid. It might have length zero (0). + /// The parameter is . + /// The operating system platform does not support this operation on remote computers. + /// 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. + /// A problem occurred accessing an underlying system API. + /// + /// + /// + /// public static Process[] GetProcesses(string machineName) { bool isRemoteMachine = ProcessManager.IsRemoteMachine(machineName); @@ -1069,22 +1517,38 @@ public static Process[] GetProcesses(string machineName) return processes; } - /// - /// - /// Returns a new - /// component and associates it with the current active process. - /// - /// + /// Gets a new component and associates it with the currently active process. + /// A new component associated with the process resource that is running the calling application. + /// Use this method to create a new 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. + /// 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. + /// + /// + /// + /// public static Process GetCurrentProcess() { return new Process(".", false, Environment.ProcessId, null); } - /// - /// - /// Raises the event. - /// - /// + /// Raises the event. + /// is the API method that raises the event. Calling causes the event to occur and is the only way to raise the event using the component. is primarily used when deriving classes from the component. + /// As an alternative to , you can write your own event handler. You create your own event handler delegate and your own event-handling method. + /// [!NOTE] + /// > 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/). + /// The following example shows how to use the method in a derived class. + /// + /// protected void OnExited() { EventHandler? exited = _onExited; @@ -1120,14 +1584,15 @@ private void RaiseOnExited() } } - /// - /// - /// Discards any information about the associated process - /// that has been cached inside the process component. After is called, the - /// first request for information for each property causes the process component - /// to obtain a new value from the associated process. - /// - /// + /// Discards any information about the associated process that has been cached inside the process component. + /// After 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. + /// 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. + /// public void Refresh() { _processInfo = null; @@ -1188,15 +1653,22 @@ private void SetProcessId(int processId) /// Additional optional configuration hook after a process ID is set. partial void ConfigureAfterProcessIdSet(); - /// - /// - /// Starts a process specified by the property of this - /// component and associates it with the - /// . If a process resource is reused - /// rather than started, the reused process is associated with this - /// component. - /// - /// + /// Starts (or reuses) the process resource that is specified by the property of this component and associates it with the component. + /// if a process resource is started; if no new process resource is started (for example, if an existing process is reused). + /// + /// No file name was specified in the component's . + /// -or- + /// The member of the property is while , , or is . + /// There was an error in opening the associated file. + /// The process object has already been disposed. + /// Method not supported on operating systems without shell support such as Nano Server (.NET Core only). + /// + /// + /// + /// + /// public bool Start() { Close(); @@ -1231,13 +1703,21 @@ public bool Start() return StartCore(startInfo); } - /// - /// - /// Starts a process resource by specifying the name of a - /// document or application file. Associates the process resource with a new - /// component. - /// - /// + /// Starts a process resource by specifying the name of a document or application file and associates the resource with a new component. + /// The name of a document or application file to run in the process. + /// 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. + /// + /// An error occurred when opening the associated file. + /// -or- + /// The file specified in the could not be found. + /// The process object has already been disposed. + /// The PATH environment variable has a string containing quotes. + /// + /// + /// + /// public static Process Start(string fileName) { // the underlying Start method can only return null on Windows platforms, @@ -1246,14 +1726,26 @@ public static Process Start(string fileName) return Start(new ProcessStartInfo(fileName))!; } - /// - /// - /// Starts a process resource by specifying the name of an - /// application and a set of command line arguments. Associates the process resource - /// with a new - /// component. - /// - /// + /// 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. + /// The name of an application file to run in the process. + /// Command-line arguments to pass when starting the process. + /// 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. + /// + /// The or parameter is . + /// An error occurred when opening the associated file. + /// -or- + /// The file specified in the could not be found. + /// -or- + /// The sum of the length of the arguments and the length of the full path to the process exceeds 2080. The error message associated with this exception can be one of the following: "The data area passed to a system call is too small." or "Access is denied." + /// The process object has already been disposed. + /// The PATH environment variable has a string containing quotes. + /// + /// + /// + /// + /// public static Process Start(string fileName, string arguments) { // the underlying Start method can only return null on Windows platforms, @@ -1262,9 +1754,11 @@ public static Process Start(string fileName, string arguments) return Start(new ProcessStartInfo(fileName, arguments))!; } - /// - /// Starts a process resource by specifying the name of an application and a set of command line arguments - /// + /// Starts a process resource by specifying the name of an application and a set of command line arguments. + /// The name of a document or application file to run in the process. + /// The command-line arguments to pass when starting the process. + /// A new that is associated with the process resource, or if no process resource is started. + /// Each argument will be escaped automatically if required. public static Process Start(string fileName, IEnumerable arguments) { if (fileName == null) @@ -1281,14 +1775,30 @@ public static Process Start(string fileName, IEnumerable arguments) return Start(startInfo)!; } - /// - /// - /// Starts a process resource specified by the process start - /// information passed in, for example the file name of the process to start. - /// Associates the process resource with a new - /// component. - /// - /// + /// 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. + /// The that contains the information that is used to start the process, including the file name and any command-line arguments. + /// 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. + /// + /// No file name was specified in the parameter's property. + /// -or- + /// The property of the parameter is and the , , or property is also . + /// -or- + /// The property of the parameter is and the property is not or empty or the property is not . + /// The parameter is . + /// The process object has already been disposed. + /// An error occurred when opening the associated file. + /// -or- + /// The file specified in the parameter's property could not be found. + /// -or- + /// The sum of the length of the arguments and the length of the full path to the process exceeds 2080. The error message associated with this exception can be one of the following: "The data area passed to a system call is too small." or "Access is denied." + /// Method not supported on operating systems without shell support such as Nano Server (.NET Core only). + /// + /// + /// + /// + /// public static Process? Start(ProcessStartInfo startInfo) { Process process = new Process(); @@ -1338,6 +1848,15 @@ private void StopWatchingForExit() } } + /// Formats the process's name as a string, combined with the parent component type, if applicable. + /// The , combined with the base component's return value. + /// + /// 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. + /// public override string ToString() { if (Associated) @@ -1351,21 +1870,49 @@ public override string ToString() return base.ToString(); } - /// - /// - /// Instructs the component to wait - /// indefinitely for the associated process to exit. - /// - /// + /// Instructs the component to wait indefinitely for the associated process to exit. + /// + /// The wait setting could not be accessed. + /// No process has been set, and a from which the property can be determined does not exist. + /// -or- + /// There is no process associated with this object. + /// -or- + /// You are attempting to call for a process that is running on a remote computer. This method is available only for processes that are running on the local computer. + /// + /// + /// + /// + /// + /// + /// public void WaitForExit() { WaitForExit(Timeout.Infinite); } - /// - /// Instructs the Process component to wait the specified number of milliseconds for - /// the associated process to exit. - /// + /// Instructs the component to wait the specified number of milliseconds for the associated process to exit. + /// The amount of time, in milliseconds, to wait for the associated process to exit. A value of 0 specifies an immediate return, and a value of -1 specifies an infinite wait. + /// if the associated process has exited; otherwise, . + /// + /// The wait setting could not be accessed. + /// No process has been set, and a from which the property can be determined does not exist. + /// -or- + /// There is no process associated with this object. + /// -or- + /// You are attempting to call for a process that is running on a remote computer. This method is available only for processes that are running on the local computer. + /// is a negative number other than -1, which represents an infinite time-out. + /// + /// + /// + /// + /// + /// + /// + /// public bool WaitForExit(int milliseconds) { bool exited = WaitForExitCore(milliseconds); @@ -1376,17 +1923,10 @@ public bool WaitForExit(int milliseconds) return exited; } - /// - /// Instructs the Process component to wait for the associated process to exit, or - /// for the to be canceled. - /// - /// - /// Calling this method will set to . - /// - /// - /// A task that will complete when the process has exited, cancellation has been requested, - /// or an error occurs. - /// + /// Instructs the process component to wait for the associated process to exit, or for the to be cancelled. + /// An optional token to cancel the asynchronous operation. + /// A task that will complete when the process has exited, cancellation has been requested, or an error occurs. + /// Calling this method will set to . public async Task WaitForExitAsync(CancellationToken cancellationToken = default) { // Because the process has already started by the time this method is called, @@ -1498,14 +2038,20 @@ async ValueTask WaitUntilOutputEOF() } } - /// - /// - /// Instructs the component to start - /// reading the StandardOutput stream asynchronously. The user can register a callback - /// that will be called when a line of data terminated by \n,\r or \r\n is reached, or the end of stream is reached - /// then the remaining information is returned. The user can add an event handler to OutputDataReceived. - /// - /// + /// Begins asynchronous read operations on the redirected stream of the application. + /// + /// The property is . + /// -or- + /// An asynchronous read operation is already in progress on the stream. + /// -or- + /// The stream has been used by a synchronous read operation. + /// + /// + /// + /// + /// public void BeginOutputReadLine() { if (_outputStreamReadMode == StreamReadMode.Undefined) @@ -1535,15 +2081,20 @@ public void BeginOutputReadLine() _output.BeginReadLine(); } - - /// - /// - /// Instructs the component to start - /// reading the StandardError stream asynchronously. The user can register a callback - /// that will be called when a line of data terminated by \n,\r or \r\n is reached, or the end of stream is reached - /// then the remaining information is returned. The user can add an event handler to ErrorDataReceived. - /// - /// + /// Begins asynchronous read operations on the redirected stream of the application. + /// + /// The property is . + /// -or- + /// An asynchronous read operation is already in progress on the stream. + /// -or- + /// The stream has been used by a synchronous read operation. + /// + /// + /// + /// + /// public void BeginErrorReadLine() { if (_errorStreamReadMode == StreamReadMode.Undefined) @@ -1575,12 +2126,16 @@ public void BeginErrorReadLine() _error.BeginReadLine(); } - /// - /// - /// Instructs the component to cancel the asynchronous operation - /// specified by BeginOutputReadLine(). - /// - /// + /// Cancels the asynchronous read operation on the redirected stream of an application. + /// + /// The stream is not enabled for asynchronous read operations. + /// + /// + /// + /// + /// public void CancelOutputRead() { CheckDisposed(); @@ -1596,12 +2151,16 @@ public void CancelOutputRead() _pendingOutputRead = false; } - /// - /// - /// Instructs the component to cancel the asynchronous operation - /// specified by BeginErrorReadLine(). - /// - /// + /// Cancels the asynchronous read operation on the redirected stream of an application. + /// + /// The stream is not enabled for asynchronous read operations. + /// + /// + /// + /// + /// public void CancelErrorRead() { CheckDisposed(); diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModule.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModule.cs index b45513b076c60..164f4dce0d4d1 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModule.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModule.cs @@ -5,11 +5,18 @@ namespace System.Diagnostics { - /// - /// A process module component represents a DLL or EXE loaded into - /// a particular process. Using this component, you can determine - /// information about the module. - /// + /// Represents a.dll or .exe file that is loaded into a particular process. + /// A module is an executable file or a dynamic link library (DLL). Each process consists of one or more modules. You can use this class to get information about the module. + /// [!IMPORTANT] + /// > 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`/`catch` 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. + /// ]]> + /// The following code sample demonstrates how to use the class to get and display information about all the modules that are used by the Notepad.exe application. + /// [Designer("System.Diagnostics.Design.ProcessModuleDesigner, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] public class ProcessModule : Component { @@ -17,40 +24,84 @@ public class ProcessModule : Component internal ProcessModule() { } - /// - /// Returns the name of the Module. - /// + /// Gets the name of the process module. + /// The name of the module. + /// If the name is longer than the maximum number of characters allowed, it is truncated. + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The property is used to display the name of each module. + /// public string? ModuleName { get; internal set; } - /// - /// Returns the full file path for the location of the module. - /// + /// Gets the full path to the module. + /// The fully qualified path that defines the location of the module. + /// If the file name is longer than the maximum number of characters allowed, the file name is truncated. + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the full path information for each module. + /// public string? FileName { get; internal set; } - /// - /// Returns the memory address that the module was loaded at. - /// + /// Gets the memory address where the module was loaded. + /// The load address of the module. + /// + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the memory address where each module was loaded. + /// public IntPtr BaseAddress { get; internal set; } - /// - /// Returns the amount of memory required to load the module. This does - /// not include any additional memory allocations made by the module once - /// it is running; it only includes the size of the static code and data - /// in the module file. - /// + /// Gets the amount of memory that is required to load the module. + /// The size, in bytes, of the memory that the module occupies. + /// does not include any additional memory allocations that the module makes once it is running; it includes only the size of the static code and data in the module file. + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the amount of memory needed for each module. + /// public int ModuleMemorySize { get; internal set; } - /// - /// Returns the memory address for function that runs when the module is - /// loaded and run. - /// + /// Gets the memory address for the function that runs when the system loads and runs the module. + /// The entry point of the module. + /// [!NOTE] + /// > Due to changes in the way that Windows loads assemblies, will always return 0 on [!INCLUDE[win8](~/includes/win8-md.md)] or [!INCLUDE[win81](~/includes/win81-md.md)] and should not be relied on for those platforms. + /// ## Examples + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the name and the entry point address for each module. + /// [!code-cpp[ProcessModule_EntryPoint#1](~/samples/snippets/cpp/VS_Snippets_CLR/ProcessModule_EntryPoint/CPP/processmodule_entrypoint.cpp#1)] + /// [!code-csharp[ProcessModule_EntryPoint#1](~/samples/snippets/csharp/VS_Snippets_CLR/ProcessModule_EntryPoint/CS/processmodule_entrypoint.cs#1)] + /// [!code-vb[ProcessModule_EntryPoint#1](~/samples/snippets/visualbasic/VS_Snippets_CLR/ProcessModule_EntryPoint/VB/processmodule_entrypoint.vb#1)] + /// ]]> public IntPtr EntryPointAddress { get; internal set; } - /// - /// Returns version information about the module. - /// + /// Gets version information about the module. + /// A that contains the module's version information. + /// + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The and properties are used to display the module name and the file version information for each module. + /// public FileVersionInfo FileVersionInfo => _fileVersionInfo ?? (_fileVersionInfo = FileVersionInfo.GetVersionInfo(FileName!)); + /// Converts the name of the module to a string. + /// The value of the property. + /// + /// The following code example creates a new process for the Notepad.exe application. The code iterates through the class to obtain a object for each module in the collection. The method is used to display the name for each module. + /// public override string ToString() => $"{base.ToString()} ({ModuleName})"; } } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModuleCollection.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModuleCollection.cs index 5d56a6460c853..81a2465b8697e 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModuleCollection.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessModuleCollection.cs @@ -5,12 +5,19 @@ namespace System.Diagnostics { + /// Provides a strongly typed collection of objects. + /// A module is an executable file or a dynamic link library (DLL). Each process consists of one or more modules. You can use this class to iterate over a collection of process modules on the system. A module is identified by its module name and fully qualified file path. + /// + /// public class ProcessModuleCollection : ReadOnlyCollectionBase { + /// Initializes a new instance of the class, with no associated instances. protected ProcessModuleCollection() { } + /// Initializes a new instance of the class, using the specified array of instances. + /// An array of instances with which to initialize this instance. public ProcessModuleCollection(ProcessModule[] processModules) { InnerList.AddRange(processModules); @@ -32,10 +39,20 @@ internal ProcessModuleCollection(int capacity) public ProcessModule this[int index] => (ProcessModule)InnerList[index]!; + /// Provides the location of a specified module within the collection. + /// The whose index is retrieved. + /// The zero-based index that defines the location of the module within the . public int IndexOf(ProcessModule module) => InnerList.IndexOf(module); + /// Determines whether the specified process module exists in the collection. + /// A instance that indicates the module to find in this collection. + /// if the module exists in the collection; otherwise, . + /// A module is identified by its module name and its fully qualified file path. public bool Contains(ProcessModule module) => InnerList.Contains(module); + /// Copies an array of instances to the collection, at the specified index. + /// An array of instances to add to the collection. + /// The location at which to add the new instances. public void CopyTo(ProcessModule[] array, int index) => InnerList.CopyTo(array, index); internal void Dispose() diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessPriorityClass.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessPriorityClass.cs index aadcca93791d8..1d5732f6346ed 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessPriorityClass.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessPriorityClass.cs @@ -3,52 +3,28 @@ namespace System.Diagnostics { - /// - /// A category of priority for a process. Threads within a process - /// run at a priority which is relative to the process priority class. - /// + /// Indicates the priority that the system associates with a process. This value, together with the priority value of each thread of the process, determines each thread's base priority level. + /// A process priority class encompasses a range of thread priority levels. Threads with different priorities running in the process run relative to the process's priority class. The operating system uses the base-priority level of all executable threads to determine which thread gets the next slice of processor time. + /// Win32 uses four priority classes with seven base priority levels per class. Based on time elapsed or other boosts, the operating system can change the base priority level when a process needs to be put ahead of others for access to the processor. In addition, you can set 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. + /// public enum ProcessPriorityClass { - /// - /// Specify this class for a process with no special scheduling needs. - /// + /// Specifies that the process has no special scheduling needs. Normal = 0x20, - /// - /// Specify this class for a process whose threads run only when the system is idle. - /// The threads of the process are preempted by the threads of any process running in - /// a higher priority class. An example is a screen saver. The idle-priority class is - /// inherited by child processes. - /// + /// Specifies that the threads of this process run only when the system is idle, such as a screen saver. The threads of the process are preempted by the threads of any process running in a higher priority class. This priority class is inherited by child processes. Idle = 0x40, - /// - /// Specify this class for a process that performs time-critical tasks that must - /// be executed immediately. The threads of the process preempt the threads of - /// normal or idle priority class processes. An example is the Task List, which - /// must respond quickly when called by the user, regardless of the load on the - /// operating system. Use extreme care when using the high-priority class, because - /// a high-priority class application can use nearly all available CPU time. - /// + /// Specifies that the process performs time-critical tasks that must be executed immediately, such as the dialog, which must respond quickly when called by the user, regardless of the load on the operating system. The threads of the process preempt the threads of normal or idle priority class processes.
Use extreme care when specifying for the process's priority class, because a high priority class application can use nearly all available processor time. High = 0x80, - /// - /// Specify this class for a process that has the highest possible priority. - /// The threads of the process preempt the threads of all other processes, - /// including operating system processes performing important tasks. For example, - /// a real-time process that executes for more than a very brief interval can cause - /// disk caches not to flush or cause the mouse to be unresponsive. - /// + /// Specifies that the process has the highest possible priority.
The threads of a process with priority preempt the threads of all other processes, including operating system processes performing important tasks. Thus, a priority process that executes for more than a very brief interval can cause disk caches not to flush or cause the mouse to be unresponsive. RealTime = 0x100, - /// - /// Indicates a process that has priority above Idle but below Normal. - /// + /// Specifies that the process has priority above but below . BelowNormal = 0x4000, - /// - /// Indicates a process that has priority above Normal but below High. - /// + /// Specifies that the process has priority higher than but lower than . AboveNormal = 0x8000 } } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Win32.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Win32.cs index 6b3503675d0be..a44b55f2fb6f2 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Win32.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Win32.cs @@ -7,8 +7,36 @@ namespace System.Diagnostics { + /// Specifies a set of values that are used when you start a process. + /// is used together with the component. When you start a process using the class, you have access to process information in addition to that available when attaching to a running process. + /// You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. + /// Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. + /// Set the property to specify whether to start the process by using the operating system shell. If is set to , the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to . + /// You can change the value of any property up to the time that the process starts. After you start the process, changing these values has no effect. + /// [!NOTE] + /// > This class contains a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). + /// ]]> + /// The following code example demonstrates how to use the class to start Internet Explorer, providing the destination URLs as arguments. + /// + /// public sealed partial class ProcessStartInfo { + /// Gets the set of verbs associated with the type of file specified by the property. + /// The actions that the system can apply to the file indicated by the property. + /// The property enables you to determine the verbs that can be used with the file specified by the property. You can set the property to the value of any verb in the set. Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". + /// When you use the property, you must include the file name extension when you set the value of the property. The file name extension determines the set of possible verbs. + /// The following code example displays the defined verbs for the chosen file name. If the user selects one of the defined verbs, the example starts a new process using the selected verb and the input file name. + /// + /// public string[] Verbs { get @@ -46,6 +74,32 @@ public string[] Verbs } } + /// Gets or sets a value indicating whether to use the operating system shell to start the process. + /// if the shell should be used when starting the process; if the process should be created directly from the executable file. The default is on .NET Framework apps and on .NET Core apps. + /// Setting this property to enables you to redirect input, output, and error streams. + /// The word "shell" in this context (`UseShellExecute`) refers to a graphical shell (similar to the Windows shell) rather than command shells (for example, `bash` or `sh`) and lets users launch graphical applications or open documents. + /// [!NOTE] + /// > must be `false` if the property is not `null` or an empty string, or an will be thrown when the method is called. + /// ]]> + /// When you use the operating system shell to start processes, you can start any document (which is any registered file type associated with an executable that has a default open action) and perform operations on the file, such as printing, by using the object. When is , you can start only executables by using the object. + /// [!NOTE] + /// > must be `true` if you set the property to `true`. + /// ]]> + /// If you set the to , must be set to . + /// ### WorkingDirectory + /// The property behaves differently depending on the value of the property. When is , the property specifies the location of the executable. If is an empty string, it is assumed that the current directory contains the executable. + /// When is , the property is not used to find the executable. Instead, it is used only by the process that is started and has meaning only within the context of the new process. When is , the property can be either a fully qualified path to the executable, or a simple executable name that the system will attempt to find within folders specified by the PATH environment variable. + /// + /// An attempt to set the value to on Universal Windows Platform (UWP) apps occurs. + /// + /// + /// public bool UseShellExecute { get; set; } } } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Windows.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Windows.cs index c66ea64cfcd4d..450d77af78608 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Windows.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.Windows.cs @@ -6,13 +6,36 @@ namespace System.Diagnostics { + /// Specifies a set of values that are used when you start a process. + /// is used together with the component. When you start a process using the class, you have access to process information in addition to that available when attaching to a running process. + /// You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. + /// Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. + /// Set the property to specify whether to start the process by using the operating system shell. If is set to , the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to . + /// You can change the value of any property up to the time that the process starts. After you start the process, changing these values has no effect. + /// [!NOTE] + /// > This class contains a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). + /// ]]> + /// The following code example demonstrates how to use the class to start Internet Explorer, providing the destination URLs as arguments. + /// + /// public sealed partial class ProcessStartInfo { private string? _domain; + /// Gets or sets the user password in clear text to use when starting the process. + /// The user password in clear text. [SupportedOSPlatform("windows")] public string? PasswordInClearText { get; set; } + /// Gets or sets a value that identifies the domain to use when starting the process. If this value is , the property must be specified in UPN format. + /// The Active Directory domain to use when starting the process. If this value is , the property must be specified in UPN format. + /// This property is primarily of interest to users within enterprise environments that use Active Directory. [SupportedOSPlatform("windows")] public string Domain { @@ -20,9 +43,31 @@ public string Domain set => _domain = value; } + /// Gets or sets a value that indicates whether the Windows user profile is to be loaded from the registry. + /// if the Windows user profile should be loaded; otherwise, . The default is . + /// This property is referenced if the process is being started by using the user name, password, and domain. + /// If the value is , the user's profile in the `HKEY_USERS` registry key is loaded. Loading the profile can be time-consuming. Therefore, it is best to use this value only if you must access the information in the `HKEY_CURRENT_USER` registry key. + /// In Windows Server 2003 and Windows 2000, the profile is unloaded after the new process has been terminated, regardless of whether the process has created child processes. + /// In Windows XP, the profile is unloaded after the new process and all child processes it has created have been terminated. [SupportedOSPlatform("windows")] public bool LoadUserProfile { get; set; } + /// Gets or sets a secure string that contains the user password to use when starting the process. + /// The user password to use when starting the process. + /// [!IMPORTANT] + /// > The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. + /// ]]> + /// [!NOTE] + /// > Setting the , , and the properties in a object is the recommended practice for starting a process with user credentials. + /// ]]> + /// A object is like a object in that it has a text value. However, the value of a object is automatically encrypted, it can be modified until your application marks it as read-only, and it can be deleted from computer memory by either your application or the .NET Framework garbage collector. + /// For more information about secure strings and an example of how to obtain a password to set this property, see the class. + /// [!NOTE] + /// > If you provide a value for the property, the property must be `false`, or an will be thrown when the method is called. + /// ]]> [CLSCompliant(false)] [SupportedOSPlatform("windows")] public SecureString? Password { get; set; } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.cs index 49ff18d43ec6f..d8b831e80bcca 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessStartInfo.cs @@ -10,11 +10,24 @@ namespace System.Diagnostics { - /// - /// A set of values used to specify a process to start. This is - /// used in conjunction with the - /// component. - /// + /// Specifies a set of values that are used when you start a process. + /// is used together with the component. When you start a process using the class, you have access to process information in addition to that available when attaching to a running process. + /// You can use the class for better control over the process you start. You must at least set the property, either manually or using the constructor. The file name is any application or document. Here a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// In addition, you can set other properties that define actions to take with that file. You can specify a value specific to the type of the property for the property. For example, you can specify "print" for a document type. Additionally, you can specify property values to be command-line arguments to pass to the file's open procedure. For example, if you specify a text editor application in the property, you can use the property to specify a text file to be opened by the editor. + /// Standard input is usually the keyboard, and standard output and standard error are usually the monitor screen. However, you can use the , , and properties to cause the process to get input from or return output to a file or other device. If you use the , , or properties on the component, you must first set the corresponding value on the property. Otherwise, the system throws an exception when you read or write to the stream. + /// Set the property to specify whether to start the process by using the operating system shell. If is set to , the new process inherits the standard input, standard output, and standard error streams of the calling process, unless the , , or properties, respectively, are set to . + /// You can change the value of any property up to the time that the process starts. After you start the process, changing these values has no effect. + /// [!NOTE] + /// > This class contains a link demand at the class level that applies to all members. A is thrown when the immediate caller does not have full-trust permission. For details about security demands, see [Link Demands](/dotnet/framework/misc/link-demands). + /// ]]> + /// The following code example demonstrates how to use the class to start Internet Explorer, providing the destination URLs as arguments. + /// + /// [DebuggerDisplay("FileName={FileName}, Arguments={BuildArguments()}, WorkingDirectory={WorkingDirectory}")] public sealed partial class ProcessStartInfo { @@ -28,51 +41,119 @@ public sealed partial class ProcessStartInfo internal DictionaryWrapper? _environmentVariables; - /// - /// Default constructor. At least the - /// property must be set before starting the process. - /// + /// Initializes a new instance of the class without specifying a file name with which to start the process. + /// You must set at least the property before you start the process. The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// Optionally, you can also set other properties before you start the process. The property supplies actions to take, such as "print", with the file indicated in the property. The property supplies a way to pass command-line arguments to the file when the system opens it. public ProcessStartInfo() { } - /// - /// Specifies the name of the application or document that is to be started. - /// + /// Initializes a new instance of the class and specifies a file name such as an application or document with which to start the process. + /// An application or document with which to start a process. + /// The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// You can change the property after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. public ProcessStartInfo(string fileName) { _fileName = fileName; } - /// - /// Specifies the name of the application that is to be started, as well as a set - /// of command line arguments to pass to the application. - /// + /// Initializes a new instance of the class, specifies an application file name with which to start the process, and specifies a set of command-line arguments to pass to the application. + /// An application with which to start a process. + /// Command-line arguments to pass to the application when the process starts. + /// The file name is any application or document. In this case, a document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// You can change the or properties after you call this constructor, up to the time that the process starts. After you start the process, changing these values has no effect. public ProcessStartInfo(string fileName, string arguments) { _fileName = fileName; _arguments = arguments; } - /// - /// Specifies the set of command line arguments to use when starting the application. - /// + /// Gets or sets the set of command-line arguments to use when starting the application. + /// A single string containing the arguments to pass to the target application specified in the property. The default is an empty string (""). + /// The length of the string assigned to the `Arguments` property must be less than 32,699. + /// Arguments are parsed and interpreted by the target application, so must align with the expectations of that application. For .NET applications as demonstrated in the Examples below, spaces are interpreted as a separator between multiple arguments. A single argument that includes spaces must be surrounded by quotation marks, but those quotation marks are not carried through to the target application. To include quotation marks in the final parsed argument, triple-escape each mark. + /// If you use this property to set command-line arguments, must not contain any elements. + /// `Arguments` and , which is supported starting with .NET Core 2.1 and .NET Standard 2.1, are independent of one another. That is, the string assigned to the `Arguments` property does not populate the collection, and the members of the collection are not assigned to the `Arguments` property. + /// The first example creates a small application (argsecho.exe) that echos its arguments to the console. The second example creates an application that invokes argsecho.exe to demonstrate different variations for the `Arguments` property. + /// + /// public string Arguments { get => _arguments ?? string.Empty; set => _arguments = value; } + /// Gets a collection of command-line arguments to use when starting the application. Strings added to the list don't need to be previously escaped. + /// A collection of command-line arguments. + /// The and properties are independent of one another and only one of them can be used at the same time. The main difference between both APIs is that takes care of escaping the provided arguments and internally builds a single string that is passed to operating system when calling . So if you are not sure how to properly escape your arguments, you should choose over . + /// + /// This example adds three arguments to the process start info. + /// + /// var info = new System.Diagnostics.ProcessStartInfo("cmd.exe"); + /// info.ArgumentList.Add("/c"); + /// info.ArgumentList.Add("dir"); + /// info.ArgumentList.Add(@"C:\Program Files\dotnet"); // there is no need to escape the space, the API takes care of it + /// // or if you prefer collection property initializer syntax: + /// var info = new System.Diagnostics.ProcessStartInfo("cmd.exe") + /// { + /// ArgumentList = { + /// "/c", + /// "dir", + /// @"C:\Program Files\dotnet" + /// } + /// }; + /// // The corresponding assignment to the Arguments property is: + /// var info = new System.Diagnostics.ProcessStartInfo("cmd.exe") + /// { + /// Arguments = "/c dir \"C:\\Program Files\\dotnet\"" + /// }; + /// + /// + /// Dim info As New System.Diagnostics.ProcessStartInfo("cmd.exe") + /// info.ArgumentList.Add("/c") + /// info.ArgumentList.Add("dir") + /// info.ArgumentList.Add("C:\Program Files\dotnet") + /// ' The corresponding assignment to the Arguments property is: + /// info.Arguments = "/c dir ""C:\Program Files\dotnet""" + /// + /// public Collection ArgumentList => _argumentList ??= new Collection(); internal bool HasArgumentList => _argumentList is not null && _argumentList.Count != 0; + /// Gets or sets a value indicating whether to start the process in a new window. + /// if the process should be started without creating a new window to contain it; otherwise, . The default is . + /// If the property is or the and properties are not , the property value is ignored and a new window is created. + /// .NET Core does not support creating windows directly on Unix-like platforms, including macOS and Linux. This property is ignored on such platforms. + /// public bool CreateNoWindow { get; set; } + /// Gets search paths for files, directories for temporary files, application-specific options, and other similar information. + /// A string dictionary that provides environment variables that apply to this process and child processes. The default is . + /// Although you cannot set the property, you can modify the returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.EnvironmentVariables.Add("TempPath", "C:\\Temp")`. You must set the property to to start the process after changing the property. If is , an is thrown when the method is called. [Editor("System.Diagnostics.Design.StringDictionaryEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] public StringDictionary EnvironmentVariables => new StringDictionaryWrapper((Environment as DictionaryWrapper)!); + /// Gets the environment variables that apply to this process and its child processes. + /// A generic dictionary containing the environment variables that apply to this process and its child processes. The default is . + /// The environment variables contain search paths for files, directories for temporary files, application-specific options, and other similar information. Although you cannot directly set the property, you can modify the generic dictionary returned by the property. For example, the following code adds a TempPath environment variable: `myProcess.StartInfo.Environment.Add("TempPath", "C:\\Temp")`. You must set the property to to start the process after changing the property. If is , an is thrown when the method is called. + /// On .NET Framework applications, using the property is the same as using the property. + /// + /// + /// public IDictionary Environment { get @@ -98,21 +179,126 @@ public string Arguments } } + /// Gets or sets a value indicating whether the input for an application is read from the stream. + /// if input should be read from ; otherwise, . The default is . + /// A can read input text from its standard input stream, typically the keyboard. By redirecting the stream, you can programmatically specify the input of a process. For example, instead of using keyboard input, you can provide text from the contents of a designated file or output from another application. + /// [!NOTE] + /// > You must set to `false` if you want to set to `true`. Otherwise, writing to the stream throws an exception. + /// ]]> + /// The following example illustrates how to redirect the stream of a process. The `sort` command is a console application that reads and sorts text input. + /// The example starts the `sort` command with redirected input. It then prompts the user for text, and passes the text to the `sort` process through the redirected stream. The `sort` results are displayed to the user on the console. + /// + /// + /// public bool RedirectStandardInput { get; set; } + /// Gets or sets a value that indicates whether the textual output of an application is written to the stream. + /// if output should be written to ; otherwise, . The default is . + /// When a writes text to its standard stream, that text is typically displayed on the console. By setting to to redirect the stream, you can manipulate or suppress the output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + /// [!NOTE] + /// > You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. + /// ]]> + /// The redirected stream can be read synchronously or asynchronously. Methods such as , , and perform synchronous read operations on the output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + /// In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler (see ) for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + /// [!NOTE] + /// > The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. + /// ]]> + /// Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. + /// The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. + /// + /// 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. + /// + /// 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. + /// + /// 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. + /// + /// + /// public bool RedirectStandardOutput { get; set; } + /// Gets or sets a value that indicates whether the error output of an application is written to the stream. + /// if error output should be written to ; otherwise, . The default is . + /// When a writes text to its standard error stream, that text is typically displayed on the console. By redirecting the stream, you can manipulate or suppress the error output of a process. For example, you can filter the text, format it differently, or write the output to both the console and a designated log file. + /// [!NOTE] + /// > You must set to `false` if you want to set to `true`. Otherwise, reading from the stream throws an exception. + /// ]]> + /// The redirected stream can be read synchronously or asynchronously. Methods such as , and perform synchronous read operations on the error output stream of the process. These synchronous read operations do not complete until the associated writes to its stream, or closes the stream. + /// In contrast, starts asynchronous read operations on the stream. This method enables a designated event handler for the stream output and immediately returns to the caller, which can perform other work while the stream output is directed to the event handler. + /// [!NOTE] + /// > The application that is processing the asynchronous output should call the method to ensure that the output buffer has been flushed. + /// ]]> + /// Synchronous read operations introduce a dependency between the caller reading from the stream and the child process writing to that stream. These dependencies can cause deadlock conditions. When the caller reads from the redirected stream of a child process, it is dependent on the child. The caller waits for the read operation until the child writes to the stream or closes the stream. When the child process writes enough data to fill its redirected stream, it is dependent on the parent. The child process waits for the next write operation until the parent reads from the full stream or closes the stream. The deadlock condition results when the caller and child process wait for each other to complete an operation, and neither can continue. You can avoid deadlocks by evaluating dependencies between the caller and child process. + /// The last two examples in this section use the method to launch an executable named *Write500Lines.exe*. The following example contains its source code. + /// + /// 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. + /// + /// There is a similar issue when you read all text from both the standard output and standard error streams. The following C# code, for example, performs a read operation on both streams. It avoids the deadlock condition by performing asynchronous read operations on the stream. A deadlock condition results if the parent process calls `p.StandardOutput.ReadToEnd` followed by `p.StandardError.ReadToEnd` and the child process writes enough text to fill its error stream. The parent process would wait indefinitely for the child process to close its stream. The child process would wait indefinitely for the parent to read from the full stream. + /// + /// 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. + /// 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. + /// + /// + /// public bool RedirectStandardError { get; set; } + /// Gets or sets the preferred encoding for standard input. + /// An object that represents the preferred encoding for standard input. The default is . + /// If the value of the `StandardInputEncoding` property is , the process uses the default standard input encoding for the standard input. The `StandardInputEncoding` property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding. The application should be tested to determine which encodings the process supports. public Encoding? StandardInputEncoding { get; set; } + /// Gets or sets the preferred encoding for error output. + /// An object that represents the preferred encoding for error output. The default is . + /// If the value of the property is , the process uses the default standard error encoding for error output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding; the process will use only those encodings that it supports. The application should be tested to determine which encodings are supported. public Encoding? StandardErrorEncoding { get; set; } + /// Gets or sets the preferred encoding for standard output. + /// An object that represents the preferred encoding for standard output. The default is . + /// If the value of the property is , the process uses the default standard output encoding for the standard output. The property must be set before the process is started. Setting this property does not guarantee that the process will use the specified encoding. The application should be tested to determine which encodings the process supports. public Encoding? StandardOutputEncoding { get; set; } - /// - /// - /// Returns or sets the application, document, or URL that is to be launched. - /// - /// + /// Gets or sets the application or document to start. + /// The name of the application to start, or the name of a document of a file type that is associated with an application and that has a default open action available to it. The default is an empty string (""). + /// You must set at least the property before you start the process. The file name is any application or document. A document is defined to be any file type that has an open or default action associated with it. You can view registered file types and their associated applications for your computer by using the Folder Options dialog box, which is available through the operating system. The Advanced button leads to a dialog box that shows whether there is an open action associated with a specific registered file type. + /// The set of file types available to you depends in part on the value of the property. If is , you can start any document and perform operations on the file, such as printing, with the component. When is , you can start only executables with the component. + /// You can start a ClickOnce application by setting the property to the location (for example, a Web address) from which you originally installed the application. Do not start a ClickOnce application by specifying its installed location on your hard disk. + /// [Editor("System.Diagnostics.Design.StartFileNameEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] public string FileName @@ -121,10 +307,19 @@ public string FileName set => _fileName = value; } - /// - /// Returns or sets the initial directory for the process that is started. - /// Specify "" to if the default is desired. - /// + /// When the property is , gets or sets the working directory for the process to be started. When is , gets or sets the directory that contains the process to be started. + /// When is , the fully qualified name of the directory that contains the process to be started. When the property is , the working directory for the process to be started. The default is an empty string (""). + /// [!IMPORTANT] + /// > The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. + /// ]]> + /// If the directory is already part of the system path variable, you do not have to repeat the directory's location in this property. + /// The property behaves differently when is than when is . When is , the property specifies the location of the executable. If is an empty string, the current directory is understood to contain the executable. + /// [!NOTE] + /// > When is `true`, the working directory of the application that starts the executable is also the working directory of the executable. + /// ]]> + /// When is , the property is not used to find the executable. Instead, its value applies to the process that is started and only has meaning within the context of the new process. [Editor("System.Diagnostics.Design.WorkingDirectoryEditor, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a", "System.Drawing.Design.UITypeEditor, System.Drawing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] public string WorkingDirectory @@ -133,15 +328,41 @@ public string WorkingDirectory set => _directory = value; } + /// Gets or sets a value indicating whether an error dialog box is displayed to the user if the process cannot be started. + /// if an error dialog box should be displayed on the screen if the process cannot be started; otherwise, . The default is . + /// [!NOTE] + /// > must be `true` if you want to set to `true`. + /// ]]> public bool ErrorDialog { get; set; } + /// Gets or sets the window handle to use when an error dialog box is shown for a process that cannot be started. + /// A pointer to the handle of the error dialog box that results from a process start failure. + /// If is , the property specifies the parent window for the dialog box that is shown. It is useful to specify a parent to keep the dialog box in front of the application. public IntPtr ErrorDialogParentHandle { get; set; } + /// Gets or sets the user name to use when starting the process. If you use the UPN format, user@DNS_domain_name, the property must be . + /// The user name to use when starting the process. If you use the UPN format, user@DNS_domain_name, the property must be . + /// [!IMPORTANT] + /// > The property must be set if and are provided. If the property is not set, the default working directory is %SYSTEMROOT%\system32. + /// ]]> + /// If the property is not or an empty string, the property must be , or an will be thrown when the method is called. public string UserName { get => _userName ?? string.Empty; set => _userName = value; } + /// Gets or sets the verb to use when opening the application or document specified by the property. + /// The action to take with the file that the process opens. The default is an empty string (""), which signifies no action. + /// Each file name extension has its own set of verbs, which can be obtained by using the property. For example, the "`print`" verb will print a document specified by using . The default verb can be specified by using an empty string (""). Examples of verbs are "Edit", "Open", "OpenAsReadOnly", "Print", and "Printto". You should use only verbs that appear in the set of verbs returned by the property. + /// When you use the property, you must include the file name extension when you set the value of the property. The file name does not need to have an extension if you manually enter a value for the property. + /// The following code example starts a new process by using the specified verb and file name. This code example is part of a larger example provided for the property. + /// + /// [DefaultValue("")] public string Verb { @@ -149,6 +370,15 @@ public string Verb set => _verb = value; } + /// Gets or sets the window state to use when the process is started. + /// One of the enumeration values that indicates whether the process is started in a window that is maximized, minimized, normal (neither maximized nor minimized), or not visible. The default is . + /// + /// + /// The window style is not one of the enumeration members. [DefaultValueAttribute(System.Diagnostics.ProcessWindowStyle.Normal)] public ProcessWindowStyle WindowStyle { diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.Windows.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.Windows.cs index f46fd604e5e21..6fd1b3ea00e49 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.Windows.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.Windows.cs @@ -7,9 +7,39 @@ namespace System.Diagnostics { + /// Represents an operating system process thread. + /// Use to obtain information about a thread that is currently running on the system. Doing so allows you, for example, to monitor the thread's performance characteristics. + /// [!IMPORTANT] + /// > 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`/`catch` 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. + /// ]]> + /// A thread is a path of execution through a program. It is the smallest unit of execution that Win32 schedules. It consists of a stack, the state of the CPU registers, and an entry in the execution list of the system scheduler. + /// A process consists of one or more threads and the code, data, and other resources of a program in memory. Typical program resources are open files, semaphores, and dynamically allocated memory. Each resource of a process is shared by all that process's threads. + /// A program executes when the system scheduler gives execution control to one of the program's threads. The scheduler determines which threads should run and when. A lower-priority thread might be forced to wait while higher-priority threads complete their tasks. On multiprocessor computers, the scheduler can move individual threads to different processors, thus balancing the CPU load. + /// Each process starts with a single thread, which is known as the primary thread. Any thread can create additional threads. All the threads within a process share the address space of that process. + /// The primary thread is not necessarily located at the first index in the collection. + /// [!NOTE] + /// > Starting with the .NET Framework version 2.0, the ability to reference performance counter data on other computers has been eliminated for many of the .NET Framework methods and properties. This change was made to improve performance and to enable non-administrators to use the class. As a result, some applications that did not get exceptions in earlier versions of the .NET Framework may now get a . The methods and properties affected are too numerous to list here, but the exception information has been added to the affected member topics. + /// ]]> + /// The threads of a process execute individually and are unaware of each other unless you make them visible to each other. Threads that share common resources, however, must coordinate their work by using semaphores or another method of interprocess communication. + /// To get a collection of all the objects associated with the current process, get the property of the instance. + /// + /// public partial class ProcessThread { - /// Sets the processor that this thread would ideally like to run on. + /// Sets the preferred processor for this thread to run on. + /// The preferred processor for the thread, used when the system schedules threads, to determine which processor to run the thread on. + /// The value is zero-based. In other words, to set the thread affinity for the first processor, set the property to zero. + /// The system schedules threads on their preferred processors whenever possible. + /// A process thread can migrate from processor to processor, with each migration reloading the processor cache. Specifying a processor for a thread can improve performance under heavy system loads by reducing the number of times the processor cache is reloaded. + /// The following example demonstrates how to set the property for an instance of Notepad to the first processor. + /// + /// The system could not set the thread to start on the specified processor. + /// The process is on a remote computer. public int IdealProcessor { set @@ -24,10 +54,10 @@ public int IdealProcessor } } - /// - /// Resets the ideal processor so there is no ideal processor for this thread (e.g. - /// any processor is ideal). - /// + /// Resets the ideal processor for this thread to indicate that there is no single ideal processor. In other words, so that any processor is ideal. + /// The ideal processor could not be reset. + /// The process is on a remote computer. + /// public void ResetIdealProcessor() { // MAXIMUM_PROCESSORS == 32 on 32-bit or 64 on 64-bit, and means the thread has no preferred processor @@ -94,12 +124,28 @@ private ThreadPriorityLevel PriorityLevelCore } } - /// - /// Sets which processors the associated thread is allowed to be scheduled to run on. - /// Each processor is represented as a bit: bit 0 is processor one, bit 1 is processor - /// two, etc. For example, the value 1 means run on processor one, 2 means run on - /// processor two, 3 means run on processor one or two. - /// + /// Sets the processors on which the associated thread can run. + /// An that points to a set of bits, each of which represents a processor that the thread can run on. + /// The processor affinity of a thread is the set of processors it has a relationship to. In other words, those it can be scheduled to run on. + /// represents each processor as a bit. Bit 0 represents processor one, bit 1 represents processor two, and so on. The following table shows a subset of the possible for a four-processor system. + /// |Property value (in hexadecimal)|Valid processors| + /// |---------------------------------------|----------------------| + /// |0x0001|1| + /// |0x0002|2| + /// |0x0003|1 or 2| + /// |0x0004|3| + /// |0x0005|1 or 3| + /// |0x0007|1, 2, or 3| + /// |0x000F|1, 2, 3, or 4| + /// You can also specify the single, preferred processor for a thread by setting the property. A process thread can migrate from processor to processor, with each migration reloading the processor cache. Specifying a processor for a thread can improve performance under heavy system loads by reducing the number of times the processor cache is reloaded. + /// The following example shows how to set the property for an instance of Notepad to the first processor. + /// + /// The processor affinity could not be set. + /// The process is on a remote computer. + /// [SupportedOSPlatform("windows")] public IntPtr ProcessorAffinity { @@ -115,35 +161,49 @@ public IntPtr ProcessorAffinity } } - /// - /// Returns the amount of time the thread has spent running code inside the operating - /// system core. - /// + /// Gets the amount of time that the thread has spent running code inside the operating system core. + /// A indicating the amount of time that the thread has spent running code inside the operating system core. + /// Windows uses several different protection mechanisms, and at the root of them all is the distinction between user mode and privileged mode. corresponds to the amount of time that the application has spent running in privileged mode, inside the operating system core. The property indicates the amount of time that the application has spent running code in user mode, outside the system core. + /// User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. + /// The thread time could not be retrieved. + /// The process is on a remote computer. + /// + /// public TimeSpan PrivilegedProcessorTime { get { return GetThreadTimes().PrivilegedProcessorTime; } } - /// Returns the time the associated thread was started. + /// Gets the time that the operating system started the thread. + /// A representing the time that was on the system when the operating system started the thread. + /// The thread time could not be retrieved. + /// The process is on a remote computer. public DateTime StartTime { get { return GetThreadTimes().StartTime; } } - /// - /// Returns the amount of time the associated thread has spent utilizing the CPU. - /// It is the sum of the System.Diagnostics.ProcessThread.UserProcessorTime and - /// System.Diagnostics.ProcessThread.PrivilegedProcessorTime. - /// + /// Gets the total amount of time that this thread has spent using the processor. + /// A that indicates the amount of time that the thread has had control of the processor. + /// The property indicates the total amount of time that the system has taken the thread out of the wait state and given it priority on any processor. On a multiple processor system, this value would include time spent on each processor, if the thread used more than one processor. + /// The property is the sum of the and properties. + /// The thread time could not be retrieved. + /// The process is on a remote computer. + /// + /// public TimeSpan TotalProcessorTime { get { return GetThreadTimes().TotalProcessorTime; } } - /// - /// Returns the amount of time the associated thread has spent running code - /// inside the application (not the operating system core). - /// + /// Gets the amount of time that the associated thread has spent running code inside the application. + /// A indicating the amount of time that the thread has spent running code inside the application, as opposed to inside the operating system core. + /// Windows NT uses several different protection mechanisms, and at the root of them all is the distinction between user mode and privileged mode. corresponds to the amount of time that the application has spent running in user mode, outside the operating system core. The corresponds to the amount of time that the application has spent running code in privileged mode, inside the system core. + /// User mode restricts the application in two important ways. First, the application cannot directly access the peripherals, but instead must call the operating system core to get or set peripheral data. The operating system can thus ensure that one application does not destroy peripheral data that is needed by another. Second, the application cannot read or change data that the operating system itself maintains. This restriction prevents applications from either inadvertently or intentionally corrupting the core. If the application needs the operating system to perform an operation, it calls one of the system's routines. Many of these transition into privileged mode, perform the operation, and smoothly return to user mode. + /// The thread time could not be retrieved. + /// The process is on a remote computer. + /// + /// public TimeSpan UserProcessorTime { get { return GetThreadTimes().UserProcessorTime; } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.cs index e147573bc13bc..a655a28bbbbdd 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThread.cs @@ -6,13 +6,25 @@ namespace System.Diagnostics { - /// - /// - /// Represents a Win32 thread. This can be used to obtain - /// information about the thread, such as it's performance characteristics. This is - /// returned from the System.Diagnostics.Process.ProcessThread property of the System.Diagnostics.Process component. - /// - /// + /// Represents an operating system process thread. + /// Use to obtain information about a thread that is currently running on the system. Doing so allows you, for example, to monitor the thread's performance characteristics. + /// [!IMPORTANT] + /// > 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`/`catch` 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. + /// ]]> + /// A thread is a path of execution through a program. It is the smallest unit of execution that Win32 schedules. It consists of a stack, the state of the CPU registers, and an entry in the execution list of the system scheduler. + /// A process consists of one or more threads and the code, data, and other resources of a program in memory. Typical program resources are open files, semaphores, and dynamically allocated memory. Each resource of a process is shared by all that process's threads. + /// A program executes when the system scheduler gives execution control to one of the program's threads. The scheduler determines which threads should run and when. A lower-priority thread might be forced to wait while higher-priority threads complete their tasks. On multiprocessor computers, the scheduler can move individual threads to different processors, thus balancing the CPU load. + /// Each process starts with a single thread, which is known as the primary thread. Any thread can create additional threads. All the threads within a process share the address space of that process. + /// The primary thread is not necessarily located at the first index in the collection. + /// [!NOTE] + /// > Starting with the .NET Framework version 2.0, the ability to reference performance counter data on other computers has been eliminated for many of the .NET Framework methods and properties. This change was made to improve performance and to enable non-administrators to use the class. As a result, some applications that did not get exceptions in earlier versions of the .NET Framework may now get a . The methods and properties affected are too numerous to list here, but the exception information has been added to the affected member topics. + /// ]]> + /// The threads of a process execute individually and are unaware of each other unless you make them visible to each other. Threads that share common resources, however, must coordinate their work by using semaphores or another method of interprocess communication. + /// To get a collection of all the objects associated with the current process, get the property of the instance. + /// + /// [Designer("System.Diagnostics.Design.ProcessThreadDesigner, System.Design, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a")] public partial class ProcessThread : Component { @@ -33,37 +45,51 @@ internal ProcessThread(bool isRemoteMachine, int processId, ThreadInfo threadInf _threadInfo = threadInfo; } - /// - /// Returns the base priority of the thread which is computed by combining the - /// process priority class with the priority level of the associated thread. - /// + /// Gets the base priority of the thread. + /// The base priority of the thread, which the operating system computes by combining the process priority class with the priority level of the associated thread. + /// The is the starting priority for the process thread. You can view information about the base priority through the System Monitor's Priority Base counter. + /// The operating system computes a thread's base priority by combining the thread's priority level range with the process's priority class. You can set the process's property to one of the values in the enumeration, which are , , , , , or . You can set the thread's property to a range of values that bounds the thread's base priority. Win32 uses four priority classes with seven base priority levels per class. + /// The thread's current priority might deviate from the base priority. For example, the operating system can change the property based on the time elapsed or other boosts when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. + /// + /// + /// + /// public int BasePriority { get { return _threadInfo._basePriority; } } - /// - /// The current priority indicates the actual priority of the associated thread, - /// which may deviate from the base priority based on how the OS is currently - /// scheduling the thread. - /// + /// Gets the current priority of the thread. + /// The current priority of the thread, which may deviate from the base priority based on how the operating system is scheduling the thread. The priority may be temporarily boosted for an active thread. + /// The thread's current priority might deviate from the base priority. For example, the operating system can change the property based on the time elapsed, or other boosts, when a process must be put ahead of others for access to the processor. In addition, you can set the property to cause the system to temporarily boost the priority of a thread whenever the process is taken out of the wait state. The priority is reset when the process returns to the wait state. + /// + /// public int CurrentPriority { get { return _threadInfo._currentPriority; } } - /// - /// Returns the unique identifier for the associated thread. - /// + /// Gets the unique identifier of the thread. + /// The unique identifier associated with a specific thread. + /// The operating system reuses thread identification numbers, which identify threads only during their lifetimes. public int Id { get { return unchecked((int)_threadInfo._threadId); } } - /// - /// Returns or sets whether this thread would like a priority boost if the user interacts - /// with user interface associated with this thread. - /// + /// Gets or sets a value indicating whether the operating system should temporarily boost the priority of the associated thread whenever the main window of the thread's process receives the focus. + /// to boost the thread's priority when the user interacts with the process's interface; otherwise, . The default is . + /// When is , the system temporarily boosts the thread's priority whenever its associated process is taken out of the wait state. This action prevents other processes from interrupting the processing of the current thread. The setting affects all existing threads as well as any threads subsequently created by the process. To restore normal behavior, set the property to . + /// has an effect only when the thread is running in a process that has a set to one of the dynamic priority enumeration values (, , or ). + /// [!NOTE] + /// > Boosting the priority too high can drain resources from essential operating system and network functions. This could cause problems with other operating system tasks. + /// ]]> + /// The priority boost information could not be retrieved. + /// -or- + /// The priority boost information could not be set. + /// The process is on a remote computer. + /// public bool PriorityBoostEnabled { get @@ -81,11 +107,17 @@ public bool PriorityBoostEnabled } } - /// - /// Returns or sets the priority level of the associated thread. The priority level is - /// not an absolute level, but instead contributes to the actual thread priority by - /// considering the priority class of the process. - /// + /// Gets or sets the priority level of the thread. + /// One of the values, specifying a range that bounds the thread's priority. + /// The priority level is not a single value, but rather a range of values. The operating system computes the thread's base priority by using the process's to choose a value from the range specified in the property. + /// The thread priority level information could not be retrieved. + /// -or- + /// The thread priority level could not be set. + /// The process is on a remote computer. + /// + /// + /// + /// public ThreadPriorityLevel PriorityLevel { get @@ -104,26 +136,33 @@ public ThreadPriorityLevel PriorityLevel } } - /// - /// Returns the memory address of the function that was called when the associated - /// thread was started. - /// + /// Gets the memory address of the function that the operating system called that started this thread. + /// The thread's starting address, which points to the application-defined function that the thread executes. + /// Each process starts with a single thread, which is known as the primary thread. Any thread can create additional threads. + /// A process has a virtual address space, executable code, data, object handles, environment variables, a base priority, and minimum and maximum working set sizes. All the threads of a process share its virtual address space and system resources. In addition, each thread maintains exception handlers, a scheduling priority, and a set of structures in which the system saves the thread context while the thread is waiting to be scheduled. The thread context includes the thread's set of machine registers, the kernel stack, a thread environment block, and a user stack in the address space of the thread's process. + /// Every Windows thread actually begins execution in a system-supplied function, not the application-supplied function. The starting address for the primary thread is, therefore, the same (as it represents the address of the system-supplied function) for every Windows process in the system. However, the property allows you to get the starting function address that is specific to your application. + /// The process is on a remote computer. public IntPtr StartAddress { get { return _threadInfo._startAddress; } } - /// - /// Returns the current state of the associated thread, e.g. is it running, waiting, etc. - /// + /// Gets the current state of this thread. + /// A that indicates the thread's execution, for example, running, waiting, or terminated. + /// The property value is valid only when the value is . Therefore, check the value before you get the property. + /// The process is on a remote computer. public ThreadState ThreadState { get { return _threadInfo._threadState; } } - /// - /// Returns the reason the associated thread is waiting, if any. - /// + /// Gets the reason that the thread is waiting. + /// A representing the reason that the thread is in the wait state. + /// The property is valid only when the is . Therefore, check the value before you get the property. + /// The thread is not in the wait state. + /// The process is on a remote computer. + /// + /// public ThreadWaitReason WaitReason { get diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThreadCollection.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThreadCollection.cs index 68f2314490ad0..60a04d8462244 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThreadCollection.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessThreadCollection.cs @@ -5,21 +5,16 @@ namespace System.Diagnostics { - /// - /// [To be supplied.] - /// + /// Provides a strongly typed collection of objects. public class ProcessThreadCollection : ReadOnlyCollectionBase { - /// - /// [To be supplied.] - /// + /// Initializes a new instance of the class, with no associated instances. protected ProcessThreadCollection() { } - /// - /// [To be supplied.] - /// + /// Initializes a new instance of the class, using the specified array of instances. + /// An array of instances with which to initialize this instance. public ProcessThreadCollection(ProcessThread[] processThreads) { InnerList.AddRange(processThreads); @@ -33,49 +28,49 @@ public ProcessThread this[int index] get { return (ProcessThread)InnerList[index]!; } } - /// - /// [To be supplied.] - /// + /// Appends a process thread to the collection. + /// The thread to add to the collection. + /// The zero-based index of the thread in the collection. public int Add(ProcessThread thread) { return ((IList)InnerList).Add(thread); } - /// - /// [To be supplied.] - /// + /// Inserts a process thread at the specified location in the collection. + /// The zero-based index indicating the location at which to insert the thread. + /// The thread to insert into the collection. public void Insert(int index, ProcessThread thread) { InnerList.Insert(index, thread); } - /// - /// [To be supplied.] - /// + /// Provides the location of a specified thread within the collection. + /// The whose index is retrieved. + /// The zero-based index that defines the location of the thread within the . public int IndexOf(ProcessThread thread) { return InnerList.IndexOf(thread); } - /// - /// [To be supplied.] - /// + /// Determines whether the specified process thread exists in the collection. + /// A instance that indicates the thread to find in this collection. + /// if the thread exists in the collection; otherwise, . + /// A module is identified by its module name and its fully qualified file path. public bool Contains(ProcessThread thread) { return InnerList.Contains(thread); } - /// - /// [To be supplied.] - /// + /// Deletes a process thread from the collection. + /// The thread to remove from the collection. public void Remove(ProcessThread thread) { InnerList.Remove(thread); } - /// - /// [To be supplied.] - /// + /// Copies an array of instances to the collection, at the specified index. + /// An array of instances to add to the collection. + /// The location at which to add the new instances. public void CopyTo(ProcessThread[] array, int index) { InnerList.CopyTo(array, index); diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessWindowStyle.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessWindowStyle.cs index 9cd6fe1a071d7..ccae0ed350648 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessWindowStyle.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ProcessWindowStyle.cs @@ -3,30 +3,20 @@ namespace System.Diagnostics { - /// - /// A set of values indicating how the window should appear when starting - /// a process. - /// + /// Specified how a new window should appear when the system starts a process. + /// public enum ProcessWindowStyle { - /// - /// Show the window in a default location. - /// + /// The normal, visible window style. The system displays a window with style on the screen, in a default location. If a window is visible, the user can supply input to the window and view the window's output. Frequently, an application may initialize a new window to the style while it customizes the window's appearance, and then make the window style . Normal, - /// - /// [To be supplied.] - /// + /// The hidden window style. A window can be either visible or hidden. The system displays a hidden window by not drawing it. If a window is hidden, it is effectively disabled. A hidden window can process messages from the system or from other windows, but it cannot process input from the user or display output. Frequently, an application may keep a new window hidden while it customizes the window's appearance, and then make the window style . To use , the property must be . Hidden, - /// - /// Show the window minimized. - /// + /// The minimized window style. By default, the system reduces a minimized window to the size of its taskbar button and moves the minimized window to the taskbar. Minimized, - /// - /// Show the window maximized. - /// + /// The maximized window style. By default, the system enlarges a maximized window so that it fills the screen or, in the case of a child window, the parent window's client area. If the window has a title bar, the system automatically moves it to the top of the screen or to the top of the parent window's client area. Also, the system disables the window's sizing border and the window-positioning capability of the title bar so that the user cannot move the window by dragging the title bar. Maximized } } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadPriorityLevel.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadPriorityLevel.cs index a96bb716d1c65..66dc1de9cbfff 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadPriorityLevel.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadPriorityLevel.cs @@ -3,46 +3,32 @@ namespace System.Diagnostics { - /// - /// Specifies the priority level of a thread. The priority level is not an absolute - /// level, but instead contributes to the actual thread priority by considering the - /// priority class of the process. - /// + /// Specifies the priority level of a thread. + /// Every thread has a base-priority level determined by the thread's priority value and the priority class of its process. The operating system uses the base-priority level of all executable threads to determine which thread gets the next slice of processor time. + /// The priority level is not an absolute value, but instead is a range of priority values. The operating system computes the priority by using the process priority class to determine where, in the range specified by the property, to set the thread's priority. + /// + /// public enum ThreadPriorityLevel { - /// - /// Idle priority - /// + /// Specifies idle priority. This is the lowest possible priority value of all threads, independent of the value of the associated . Idle = -15, - /// - /// Lowest priority - /// + /// Specifies lowest priority. This is two steps below the normal priority for the associated . Lowest = -2, - /// - /// Below normal priority - /// + /// Specifies one step below the normal priority for the associated . BelowNormal = -1, - /// - /// Normal priority - /// + /// Specifies normal priority for the associated . Normal = 0, - /// - /// Above normal priority - /// + /// Specifies one step above the normal priority for the associated . AboveNormal = 1, - /// - /// Highest priority - /// + /// Specifies highest priority. This is two steps above the normal priority for the associated . Highest = 2, - /// - /// Time critical priority - /// + /// Specifies time-critical priority. This is the highest priority of all threads, independent of the value of the associated . TimeCritical = 15 } } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadState.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadState.cs index ac018ca10a9ba..40575f29a9a04 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadState.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadState.cs @@ -3,49 +3,37 @@ namespace System.Diagnostics { - /// - /// Specifies the execution state of a thread. - /// + /// Specifies the current execution state of the thread. + /// [!IMPORTANT] + /// > There are two thread state enumerations, and . The thread state enumerations are only of interest in a few debugging scenarios. Your code should never use thread state to synchronize the activities of threads. + /// ]]> + /// + /// public enum ThreadState { - /// - /// The thread has been initialized, but has not started yet. - /// + /// A state that indicates the thread has been initialized, but has not yet started. Initialized, - /// - /// The thread is in ready state. - /// + /// A state that indicates the thread is waiting to use a processor because no processor is free. The thread is prepared to run on the next available processor. Ready, - /// - /// The thread is running. - /// + /// A state that indicates the thread is currently using a processor. Running, - /// - /// The thread is in standby state. - /// + /// A state that indicates the thread is about to use a processor. Only one thread can be in this state at a time. Standby, - /// - /// The thread has exited. - /// + /// A state that indicates the thread has finished executing and has exited. Terminated, - /// - /// The thread is waiting. - /// + /// A state that indicates the thread is not ready to use the processor because it is waiting for a peripheral operation to complete or a resource to become free. When the thread is ready, it will be rescheduled. Wait, - /// - /// The thread is transitioning between states. - /// + /// A state that indicates the thread is waiting for a resource, other than the processor, before it can execute. For example, it might be waiting for its execution stack to be paged in from disk. Transition, - /// - /// The thread state is unknown. - /// + /// The state of the thread is unknown. Unknown } } diff --git a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadWaitReason.cs b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadWaitReason.cs index c68a9a229d41b..07980a6f272a0 100644 --- a/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadWaitReason.cs +++ b/src/libraries/System.Diagnostics.Process/src/System/Diagnostics/ThreadWaitReason.cs @@ -3,79 +3,51 @@ namespace System.Diagnostics { - /// - /// Specifies the reason a thread is waiting. - /// + /// Specifies the reason a thread is waiting. + /// The thread wait reason is only valid when the is . + /// public enum ThreadWaitReason { - /// - /// Thread is waiting for the scheduler. - /// + /// The thread is waiting for the scheduler. Executive, - /// - /// Thread is waiting for a free virtual memory page. - /// + /// The thread is waiting for a free virtual memory page. FreePage, - /// - /// Thread is waiting for a virtual memory page to arrive in memory. - /// + /// The thread is waiting for a virtual memory page to arrive in memory. PageIn, - /// - /// Thread is waiting for a system allocation. - /// + /// The thread is waiting for system allocation. SystemAllocation, - /// - /// Thread execution is delayed. - /// + /// Thread execution is delayed. ExecutionDelay, - /// - /// Thread execution is suspended. - /// + /// Thread execution is suspended. Suspended, - /// - /// Thread is waiting for a user request. - /// + /// The thread is waiting for a user request. UserRequest, - /// - /// Thread is waiting for event pair high. - /// + /// The thread is waiting for event pair high. EventPairHigh, - /// - /// Thread is waiting for event pair low. - /// + /// The thread is waiting for event pair low. EventPairLow, - /// - /// Thread is waiting for a local procedure call to arrive. - /// + /// The thread is waiting for a local procedure call to arrive. LpcReceive, - /// - /// Thread is waiting for reply to a local procedure call to arrive. - /// + /// The thread is waiting for reply to a local procedure call to arrive. LpcReply, - /// - /// Thread is waiting for virtual memory. - /// + /// The thread is waiting for the system to allocate virtual memory. VirtualMemory, - /// - /// Thread is waiting for a virtual memory page to be written to disk. - /// + /// The thread is waiting for a virtual memory page to be written to disk. PageOut, - /// - /// Thread is waiting for an unknown reason. - /// + /// The thread is waiting for an unknown reason. Unknown } }