Updating FileSystem.AccessControl examples (dotnet#5247)

* Updating FileSystem.AccessControl examples

- Make sure the samples are using the latest .NET 5.0 features
- Move them to sample files instead of having them directly written in the remarks

* Apply suggestions from code review

Co-authored-by: Adam Sitnik <[email protected]>

Co-authored-by: Adam Sitnik <[email protected]>

Author: carlossanlop

samples/snippets/csharp/VS_Snippets_CLR/IO.FileSystem.AccessControl/DirectoryInfoCreateDirectory.cs

@@ -0,0 +1,37 @@
+using System.IO;
+using System.Runtime.Versioning;
+using System.Security.AccessControl;
+using System.Security.Principal;
+
+namespace MyNamespace
+{
+    public class MyClassCS
+    {
+        // Attribute to address CA1416 warning:
+        // System.IO.FileSystem.AccessControl APIs are  only available on Windows
+        [SupportedOSPlatform("windows")]
+        static void Main()
+        {
+            // Create the file security object
+
+            SecurityIdentifier identity = new SecurityIdentifier(
+                WellKnownSidType.BuiltinUsersSid, // This maps to "Everyone" user group in Windows
+                null); // null is OK for this particular user group. For others, a non-empty value might be required
+            FileSystemAccessRule accessRule = new FileSystemAccessRule(identity, FileSystemRights.FullControl, AccessControlType.Allow);
+
+            DirectorySecurity expectedSecurity = new DirectorySecurity();
+            expectedSecurity.AddAccessRule(accessRule);
+
+            // Make sure the directory does not exist, then create it
+
+            string dirPath = Path.Combine(Path.GetTempPath(), "directoryToCreate");
+            DirectoryInfo dirInfo = new DirectoryInfo(dirPath);
+            if (dirInfo.Exists)
+            {
+                dirInfo.Delete(recursive: true);
+            }
+
+            dirInfo.Create(expectedSecurity);
+        }
+    }
+}

samples/snippets/csharp/VS_Snippets_CLR/IO.FileSystem.AccessControl/FileInfoCreate.cs

@@ -0,0 +1,51 @@
+using System;
+using System.IO;
+using System.Runtime.Versioning;
+using System.Security.AccessControl;
+using System.Security.Principal;
+using System.Text;
+
+namespace MyNamespace
+{
+    public class MyClassCS
+    {
+        // Attribute to address CA1416 warning:
+        // System.IO.FileSystem.AccessControl APIs are  only available on Windows
+        [SupportedOSPlatform("windows")]
+        static void Main()
+        {
+            // Create the file security object
+
+            var identity = new SecurityIdentifier(WellKnownSidType.BuiltinUsersSid, null);
+            var accessRule = new FileSystemAccessRule(identity, FileSystemRights.FullControl, AccessControlType.Allow);
+
+            var security = new FileSecurity();
+            security.AddAccessRule(accessRule);
+
+            // Make sure the file does not exist, or FileMode.CreateNew will throw
+
+            string filePath = Path.Combine(Path.GetTempPath(), "temp.txt");
+            var fileInfo = new FileInfo(filePath);
+            if (fileInfo.Exists)
+            {
+                fileInfo.Delete();
+            }
+
+            // Create the file with the specified security and write some text
+
+            using (FileStream stream = fileInfo.Create(
+                FileMode.CreateNew,
+                FileSystemRights.FullControl,
+                FileShare.ReadWrite,
+                4096, // Default buffer size
+                FileOptions.None,
+                security))
+            {
+                string text = "Hello world!";
+                byte[] writeBuffer = new UTF8Encoding(encoderShouldEmitUTF8Identifier: true).GetBytes(text);
+
+                stream.Write(writeBuffer, 0, writeBuffer.Length);
+            } // Dispose flushes the file to disk
+        }
+    }
+}

xml/System.IO/FileSystemAclExtensions.xml

@@ -64,32 +64,7 @@ This extension method was added to .NET Core to bring the functionality that was
 
 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);
-        }
-    }
-}
-```
+[!code-csharp[DirectoryInfoCreateDirectory](~/samples/snippets/csharp/VS_Snippets_CLR/IO.FileSystem.AccessControl/DirectoryInfoCreateDirectory.cs)]
 
           ]]></format>
         </remarks>
@@ -146,34 +121,9 @@ This extension method was added to .NET Core to bring the functionality that was
 
 ## 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);
+The following code example creates a new text file inside the user's temporary folder, explicitly specifying all security attributes:
 
-            fileInfo.Create(FileMode.Create, FileSystemRights.FullControl, FileShare.Read, 4096, FileOptions.None, security);
-        }
-    }
-}
-```
+[!code-csharp[FileInfoCreate](~/samples/snippets/csharp/VS_Snippets_CLR/IO.FileSystem.AccessControl/FileInfoCreate.cs)]
 
           ]]></format>
         </remarks>