Skip to content

Add documentation for Process.Kill(bool entireProcessTree) #2828

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jul 29, 2019
Merged

Add documentation for Process.Kill(bool entireProcessTree) #2828

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ab45e8f
Add documentation for Process.Kill(bool entireProcessTree)
wtgodbe Jul 25, 2019
d063abf
Update Process.xml
mairaw Jul 25, 2019
f4e7421
minor fix: parm summary in single line
carlossanlop Jul 26, 2019
9b8e826
Address feedback
wtgodbe Jul 26, 2019
61b1a6d
Address Feedback
wtgodbe Jul 26, 2019
0a2e347
Fixed bad xml element
Jul 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 66 additions & 21 deletions xml/System.Diagnostics/Process.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2054,6 +2054,44 @@ There are problems accessing the performance counter API's used to get process i
<altmember cref="M:System.Diagnostics.Process.GetProcessById(System.Int32,System.String)" />
</Docs>
</Member>
<MemberGroup MemberName="Kill">
<Docs>
<summary>To be added.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The `Kill` method forces a termination of the process, while <xref:System.Diagnostics.Process.CloseMainWindow%2A> only requests a termination.
When a process with a graphical interface is executing, its message loop is in a wait state.
The message loop executes every time a Windows message is sent to the process by the operating system.
Calling <xref:System.Diagnostics.Process.CloseMainWindow%2A> sends a request to close to the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Calling <xref:System.Diagnostics.Process.CloseMainWindow%2A> sends a request to close to the main window, which, in a well-formed application, closes child windows and revokes all running message loops for the application.
Calling <xref:System.Diagnostics.Process.CloseMainWindow%2A> 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 <xref:System.Diagnostics.Process.CloseMainWindow%2A> does not force the application to quit.
The application can ask for user verification before quitting, or it can refuse to quit.
To force the application to quit, use the `Kill` method.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To force the application to quit, use the `Kill` method.
To force the application to quit, use the `Kill` method.

The behavior of <xref:System.Diagnostics.Process.CloseMainWindow%2A> is identical to that of a user closing an application's main window using the system menu.
Therefore, the request to exit the process by closing the main window does not force the application to quit immediately.

> [!NOTE]
> The <xref:System.Diagnostics.Process.Kill%2A> method executes asynchronously.
> After calling the `Kill` method, call the <xref:System.Diagnostics.Process.WaitForExit%2A> method to wait for the process to exit, or check the <xref:System.Diagnostics.Process.HasExited%2A> property to determine if the process has exited.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To make very clear that these ways of checking exit status only apply to the current process instance, maybe add something along the lines of the following?

"Note: WaitForExit() and HasExited do not reflect the status of descendant processes. When Kill(entireProcessTree: true) is used, WaitForExit() and HasExited will indicate that exiting has completed after the given process exits, even if all descendants have not yet exited."


Data edited by the process or resources allocated to the process can be lost if you call `Kill`.
`Kill` causes an abnormal process termination and should be used only when necessary.
<xref:System.Diagnostics.Process.CloseMainWindow%2A> enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface.
If <xref:System.Diagnostics.Process.CloseMainWindow%2A> fails, you can use `Kill` to terminate the process.
`Kill` is the only way to terminate processes that do not have graphical interfaces.

You can call `Kill` and <xref:System.Diagnostics.Process.CloseMainWindow%2A> 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.

> [!NOTE]
> If the call to the `Kill` method is made while the process is currently terminating, a <xref:System.ComponentModel.Win32Exception> is thrown for Access Denied.

]]></format>
</remarks>
</Docs>
</MemberGroup>
<Member MemberName="Kill">
<MemberSignature Language="C#" Value="public void Kill ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance void Kill() cil managed" />
Expand Down Expand Up @@ -2086,24 +2124,7 @@ There are problems accessing the performance counter API's used to get process i
<Parameters />
<Docs>
<summary>Immediately stops the associated process.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
<xref:System.Diagnostics.Process.Kill%2A> forces a termination of the process, while <xref:System.Diagnostics.Process.CloseMainWindow%2A> only requests a termination. When a process with a graphical interface is executing, its message loop is in a wait state. The message loop executes every time a Windows message is sent to the process by the operating system. Calling <xref:System.Diagnostics.Process.CloseMainWindow%2A> sends a request to close to 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 <xref:System.Diagnostics.Process.CloseMainWindow%2A> 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 <xref:System.Diagnostics.Process.Kill%2A> method. The behavior of <xref:System.Diagnostics.Process.CloseMainWindow%2A> is identical to that of a user closing an application's main window using the system menu. Therefore, the request to exit the process by closing the main window does not force the application to quit immediately.

> [!NOTE]
> The <xref:System.Diagnostics.Process.Kill%2A> method executes asynchronously. After calling the <xref:System.Diagnostics.Process.Kill%2A> method, call the <xref:System.Diagnostics.Process.WaitForExit%2A> method to wait for the process to exit, or check the <xref:System.Diagnostics.Process.HasExited%2A> property to determine if the process has exited.

Data edited by the process or resources allocated to the process can be lost if you call <xref:System.Diagnostics.Process.Kill%2A>. <xref:System.Diagnostics.Process.Kill%2A> causes an abnormal process termination and should be used only when necessary. <xref:System.Diagnostics.Process.CloseMainWindow%2A> enables an orderly termination of the process and closes all windows, so it is preferable for applications with an interface. If <xref:System.Diagnostics.Process.CloseMainWindow%2A> fails, you can use <xref:System.Diagnostics.Process.Kill%2A> to terminate the process. <xref:System.Diagnostics.Process.Kill%2A> is the only way to terminate processes that do not have graphical interfaces.

You can call <xref:System.Diagnostics.Process.Kill%2A> and <xref:System.Diagnostics.Process.CloseMainWindow%2A> 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.

> [!NOTE]
> If the call to the <xref:System.Diagnostics.Process.Kill%2A> method is made while the process is currently terminating, a <xref:System.ComponentModel.Win32Exception> is thrown for Access Denied.

]]></format>
</remarks>
<remarks>To be added.</remarks>
<exception cref="T:System.ComponentModel.Win32Exception">The associated process could not be terminated.

-or-
Expand Down Expand Up @@ -2150,9 +2171,33 @@ There are problems accessing the performance counter API's used to get process i
<Parameter Name="entireProcessTree" Type="System.Boolean" Index="0" FrameworkAlternate="netcore-3.0" />
</Parameters>
<Docs>
<param name="entireProcessTree">To be added.</param>
<summary>To be added.</summary>
<param name="entireProcessTree"><see langword="true" /> to kill the associated process and its descendants; <see langword="false" /> to kill only the associated process.</param>
<summary>Immediately stops the associated process, and optionally all of its child/descendent processes.</summary>
<remarks>To be added.</remarks>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: Drop the word "all" above (from "optionally all of its child...") and note here that, when set to true, processes where the call lacks permissions to view details will be silently skipped by the descendant termination process because the termination process is unable to determine whether those processes are descendants.

<exception cref="T:System.ComponentModel.Win32Exception">The associated process could not be terminated.

-or-

The process is terminating.

-or-

The associated process is a Win16 executable.</exception>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aren't this and line 2136 legacy conditions -- perhaps they should be deleted? (Are there still Win16 executables running on .NET Framework?)

<exception cref="T:System.NotSupportedException">You are attempting to call <see cref="M:System.Diagnostics.Process.Kill" /> for a process that is running on a remote computer. The method is available only for processes running on the local computer.</exception>
<exception cref="T:System.InvalidOperationException">The process has already exited.

-or-

There is no process associated with this <see cref="T:System.Diagnostics.Process" /> object.

-or-

The calling process is a member of the associated process' descendant tree.</exception>
<exception cref="T:System.AggregateException">Not all processes in the associated process' descendant tree could be terminated.</exception>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<altmember cref="M:System.Environment.Exit(System.Int32)" />
<altmember cref="M:System.Diagnostics.Process.CloseMainWindow" />
<altmember cref="M:System.Diagnostics.Process.Start" />
</Docs>
</Member>
<Member MemberName="LeaveDebugMode">
Expand Down Expand Up @@ -6213,4 +6258,4 @@ There is a similar issue when you read all text from both the standard output an
</Docs>
</Member>
</Members>
</Type>
</Type>