Add notes about using impersonation with async/await (dotnet#3994)

Added a warning about using `WindowsIdentity.Impersonate` with the async/await pattern, recommending `RunImpersonated` instead.

Author: kouvel

xml/System.Security.Principal/WindowsIdentity.xml

@@ -1241,6 +1241,9 @@ Application code does not call this method; it is automatically invoked during g
 ## Remarks  
  On Windows NT platforms, the current user must have sufficient rights to allow impersonation.  
   
+> [!WARNING]
+>  Avoid using this method with the async/await pattern. In some cases it may lead to reliability issues due to impersonation not being reverted even if the resulting `WindowsImpersonationContext` is disposed. Use `RunImpersonated` instead.  
+  
    
   
 ## Examples  
@@ -1306,6 +1309,9 @@ Application code does not call this method; it is automatically invoked during g
   
  For more information about calls to unmanaged code, see [Consuming Unmanaged DLL Functions](~/docs/framework/interop/consuming-unmanaged-dll-functions.md).  
   
+> [!WARNING]
+>  Avoid using this method with the async/await pattern. In some cases it may lead to reliability issues due to impersonation not being reverted even if the resulting `WindowsImpersonationContext` is disposed. Use `RunImpersonated` instead.  
+  
    
   
 ## Examples  
@@ -1709,6 +1715,13 @@ Application code does not call this method; it is automatically invoked during g
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
+## Remarks  
+  
+> [!NOTE]
+>  This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, the generic overload of this method may be used with an async delegate argument so that the resulting task may be awaited.  
+  
+   
+  
 ## Examples  
  The following example demonstrates the use of the <xref:System.Security.Principal.WindowsIdentity> class to impersonate a user.  
   
@@ -1834,6 +1847,13 @@ public class ImpersonationDemo
         <remarks>
           <format type="text/markdown"><![CDATA[  
   
+## Remarks  
+  
+> [!NOTE]
+>  This method may be used reliably with the async/await pattern, unlike `Impersonate`. In an async method, this method may be used with an async delegate argument so that the resulting task may be awaited.  
+  
+   
+  
 ## Examples  
  The following example demonstrates the use of the <xref:System.Security.Principal.WindowsIdentity> class to impersonate a user.