Add note on xplat support for Encrypt/Decrypt on .NET Core (dotnet#2259)

SeanKilleen · Ron Petrusha · commit c55b0f51fad0 · 2019-04-09T08:15:50.000-07:00
* Add note on xplat support for Encrypt/Decrypt on .NET Core * Update xml/System.IO/File.xml @rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <SeanKilleen@gmail.com> * Update xml/System.IO/File.xml @rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <SeanKilleen@gmail.com> * Update xml/System.IO/File.xml @rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <SeanKilleen@gmail.com> * Update xml/System.IO/File.xml @rpetrusha feedback on language 👍 Co-Authored-By: SeanKilleen <SeanKilleen@gmail.com> * use note format instead * update styling of note * Changes per feedback
diff --git a/xml/System.IO/File.xml b/xml/System.IO/File.xml
@@ -1332,15 +1332,18 @@
   
 ## Remarks  
  The <xref:System.IO.File.Decrypt%2A> method allows you to decrypt a file that was encrypted using the <xref:System.IO.File.Encrypt%2A> method.  The <xref:System.IO.File.Decrypt%2A> method can decrypt only files that were encrypted using the current user account.  
-  
+
+ > [!IMPORTANT]
+ > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.
+ > 
+ > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows.
+
  The <xref:System.IO.File.Decrypt%2A> method requires exclusive access to the file being decrypted, and will raise an exception if another process is using the file. If the file is not encrypted, <xref:System.IO.File.Decrypt%2A> will return a nonzero value, which indicates success.  
   
  Both the <xref:System.IO.File.Encrypt%2A> method and the <xref:System.IO.File.Decrypt%2A> method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method.  
   
  The current file system must be formatted as NTFS and the current operating system must be Windows NT or later.  
-  
    
-  
 ## Examples  
  The following code example uses the <xref:System.IO.File.Encrypt%2A> method and the <xref:System.IO.File.Decrypt%2A> method to encrypt and then decrypt a file. The file must exist for the example to work.  
   
@@ -1511,10 +1514,14 @@
         <summary>Encrypts a file so that only the account used to encrypt the file can decrypt it.</summary>
         <remarks>
           <format type="text/markdown"><![CDATA[  
-  
 ## Remarks  
  The <xref:System.IO.File.Encrypt%2A> method allows you to encrypt a file so that only the account used to call this method can decrypt it. Use the <xref:System.IO.File.Decrypt%2A> method to decrypt a file encrypted by the <xref:System.IO.File.Encrypt%2A> method.  
-  
+
+ > [!IMPORTANT]
+ > This API is only supported on Windows platforms that are able to use the NTFS Encrypting File System (EFS). Any attempt to use this on non-Windows systems, Windows Home Edition systems, or non-NTFS drives results in a <xref:System.PlatformNotSupportedException> or <xref:System.NotSupportedException>, depending on the situation.
+ > 
+ > Use of this API in .NET Core is not recommended; it is included to enable portability for applications that move to .NET Core but still explicitly target Windows.
+
  The <xref:System.IO.File.Encrypt%2A> method requires exclusive access to the file being encrypted, and will fail if another process is using the file.  
   
  Both the <xref:System.IO.File.Encrypt%2A> method and the <xref:System.IO.File.Decrypt%2A> method use the cryptographic service provider (CSP) installed on the computer and the file encryption keys of the process calling the method.  
@@ -1523,8 +1530,6 @@
   
  The current file system must be formatted as NTFS.  
   
-   
-  
 ## Examples  
  The following code example uses the <xref:System.IO.File.Encrypt%2A> method and the <xref:System.IO.File.Decrypt%2A> method to encrypt and then decrypt a file. The file must exist for the example to work.  
   
