Add usage examples for the new FileSystemAclExtensions file and directory creation methods (#3781)

* Add usage examples for the new FileSystemAclExtensions file and directory creation methods

* suggestions by Thraka

* suggestions by mairaw

Co-Authored-By: Maira Wenzel <[email protected]>

* Additional comments for legacy methods

Co-authored-by: Maira Wenzel <[email protected]>

Author: carlossanlop

xml/System.IO/DirectoryInfo.xml

@@ -275,6 +275,35 @@
   
  For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md).  
   
+> [!IMPORTANT]
+> This method was ported to .NET Core 3.1 as an extension method of the `FileSystemAclExtensions` class as part of the `System.Security.AccessControl` assembly: <xref:System.IO.FileSystemAclExtensions.Create(System.IO.DirectoryInfo,System.Security.AccessControl.DirectorySecurity)>.
+
+## Examples
+
+The following code example creates a new directory inside the user's temporary folder with the specified directory security attributes:
+
+```csharp
+using System.IO;
+using System.Security.AccessControl;
+using System.Security.Principal;
+namespace ConsoleApp
+{
+    class Program
+    {
+        static void Main()
+        {
+            DirectorySecurity security = new DirectorySecurity();
+            SecurityIdentifier identity = new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null);
+            FileSystemAccessRule accessRule = new FileSystemAccessRule(identity, FileSystemRights.FullControl, AccessControlType.Allow);
+            security.AddAccessRule(accessRule);
+            string path = Path.Combine(Path.GetTempPath(), "directoryToCreate");
+            DirectoryInfo dirInfo = new DirectoryInfo(path);
+            dirInfo.Create(security);
+        }
+    }
+}
+```
+
  ]]></format>
         </remarks>
         <exception cref="T:System.IO.IOException">The directory specified by <paramref name="path" /> is read-only or is not empty.</exception>

xml/System.IO/File.xml

@@ -1222,6 +1222,9 @@
   
  For a list of common I/O tasks, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md).  
   
+> [!IMPORTANT]
+> This method was ported to .NET Core 3.1 in the following form: <xref:System.IO.FileSystemAclExtensions.Create(System.IO.FileInfo,System.IO.FileMode,System.Security.AccessControl.FileSystemRights,System.IO.FileShare,System.Int32,System.IO.FileOptions,System.Security.AccessControl.FileSecurity)>.
+
  ]]></format>
         </remarks>
         <exception cref="T:System.UnauthorizedAccessException">The caller does not have the required permission.  

xml/System.IO/FileStream.xml

@@ -1542,7 +1542,8 @@
   
  For a list of common file and directory operations, see [Common I/O Tasks](~/docs/standard/io/common-i-o-tasks.md).  
   
-   
+ > [!IMPORTANT]
+ > This constructor does not exist in .NET Core. Instead, starting in .NET Core 3.1, you can use the following extension method of the `FileSystemAclExtensions` class inside the `System.Security.AccessControl` assembly: <xref:System.IO.FileSystemAclExtensions.Create(System.IO.FileInfo,System.IO.FileMode,System.Security.AccessControl.FileSystemRights,System.IO.FileShare,System.Int32,System.IO.FileOptions,System.Security.AccessControl.FileSecurity)>.
   
 ## Examples  
  The following example writes data to a file and then reads the data using the <xref:System.IO.FileStream> object.  

xml/System.IO/FileSystemAclExtensions.xml

@@ -54,7 +54,38 @@
 
 ## Remarks
 
-This extension method was added to .NET Core to bring the functionality that was provided by the `System.IO.DirectoryInfo.Create(System.Security.AccessControl.DirectorySecurity)` .NET Framework method.
+This extension method was added to .NET Core to bring the functionality that was provided by the [DirectoryInfo.Create(DirectorySecurity)](https://docs.microsoft.com/dotnet/api/system.io.directoryinfo.create?view=netframework-4.8#System_IO_DirectoryInfo_Create_System_Security_AccessControl_DirectorySecurity_) .NET Framework method.
+
+## Examples
+
+The following code example creates a new directory inside the user's temporary folder with the specified directory security attributes:
+
+```csharp
+using System.IO;
+using System.Security.AccessControl;
+using System.Security.Principal;
+
+namespace ConsoleApp
+{
+    class Program
+    {
+        static void Main()
+        {
+            DirectorySecurity security = new DirectorySecurity();
+
+            SecurityIdentifier identity = new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null);
+            FileSystemAccessRule accessRule = new FileSystemAccessRule(identity, FileSystemRights.FullControl, AccessControlType.Allow);
+            security.AddAccessRule(accessRule);
+
+            string path = Path.Combine(Path.GetTempPath(), "directoryToCreate");
+
+            DirectoryInfo dirInfo = new DirectoryInfo(path);
+
+            dirInfo.Create(security);
+        }
+    }
+}
+```
 
           ]]></format>
         </remarks>
@@ -102,7 +133,41 @@ This extension method was added to .NET Core to bring the functionality that was
 
 ## Remarks
 
-This extension method was added to .NET Core to bring the functionality that was provided by the `System.IO.FileStream.#ctor(System.String,System.IO.FileMode,System.Security.AccessControl.FileSystemRights,System.IO.FileShare,System.Int32,System.IO.FileOptions,System.Security.AccessControl.FileSecurity)` .NET Framework constructor.
+This extension method was added to .NET Core to bring the functionality that was provided by:
+
+- The [FileStream(String, FileMode, FileSystemRights, FileShare, Int32, FileOptions, FileSecurity)](https://docs.microsoft.com/dotnet/api/system.io.filestream.-ctor?view=netframework-4.8#System_IO_FileStream__ctor_System_String_System_IO_FileMode_System_Security_AccessControl_FileSystemRights_System_IO_FileShare_System_Int32_System_IO_FileOptions_System_Security_AccessControl_FileSecurity_) .NET Framework constructor.
+- The [File.Create(String, Int32, FileOptions, FileSecurity](https://docs.microsoft.com/en-us/dotnet/api/system.io.file.create?view=netframework-4.8#System_IO_File_Create_System_String_System_Int32_System_IO_FileOptions_System_Security_AccessControl_FileSecurity_) .NET Framework method.
+
+## Examples
+
+The following code example creates a new text file (with the default buffer size of 4096) inside the user's temporary folder with the specified file security attributes:
+
+```csharp
+using System.IO;
+using System.Security.AccessControl;
+using System.Security.Principal;
+
+namespace ConsoleApp
+{
+    class Program
+    {
+        static void Main()
+        {
+            FileSecurity security = new FileSecurity();
+
+            SecurityIdentifier identity = new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null);
+            FileSystemAccessRule accessRule = new FileSystemAccessRule(identity, FileSystemRights.FullControl, AccessControlType.Allow);
+            security.AddAccessRule(accessRule);
+
+            string path = Path.Combine(Path.GetTempPath(), "fileToCreate.txt");
+
+            FileInfo fileInfo = new FileInfo(path);
+
+            fileInfo.Create(FileMode.Create, FileSystemRights.FullControl, FileShare.Read, 4096, FileOptions.None, security);
+        }
+    }
+}
+```
 
           ]]></format>
         </remarks>