feat: Add extension to IFileSystem to allow using pattern to delete files / directories (#41)

MattKotsenas · web-flow · commit f75aa55fd6e3 · 2023-08-08T10:12:57.000+02:00
* Add DisposableDirectory and unit tests

* Add DisposableFile and unit tests

* Add CreateDisposableDirectory extension method

* Add CreateDisposableFile extension method

* Add example usage in README

* Do attribute refresh on Dispose to keep object state in sync between RAII and filesystem object

* Make DisposableFile / DisposableDirectory internal, return an IDisposable from extension method instead, and add InternalsVisibleTo in Directory.Build.props

* Extract random temp path generation into helper method

* Create a base `DisposableFileSystemInfo` class to DRY out Dispose pattern

* Move random temp path extension to `IPath`

* Move the Refresh call into DisposableFileSystemInfoBase to DRY out code

* Make IDisposable implementations public and provide custom factory

* Suppress Codacity warning for out param

* Fix README example

* Fix xmldocs for overloads
diff --git a/README.md b/README.md
@@ -49,4 +49,34 @@ using (var stream = current.File("test.txt").Create())
 //create a "test.txt" file without extension
 using (var stream = current.FileSystem.FileInfo.FromFileName(current.FileSystem.Path.Combine(current.FullName, "test.txt")).Create())
     stream.Dispose();
+```
+
+## Automatic cleanup with Disposable extensions
+
+Use `CreateDisposableDirectory` or `CreateDisposableFile` to create a `IDirectoryInfo` or `IFileInfo` that's automatically
+deleted when the returned `IDisposable` is disposed.
+
+```csharp
+var fs = new FileSystem();
+
+//with extension
+using (fs.CreateDisposableDirectory(out IDirectoryInfo dir))
+{
+    Console.WriteLine($"This directory will be deleted when control leaves the using block: '{dir.FullName}'");
+}
+
+//without extension
+var temp = fs.Path.GetTempPath();
+var fileName = fs.Path.GetRandomFileName();
+var path = fs.Path.Combine(temp, fileName);
+
+try
+{
+    IDirectoryInfo dir = fs.Directory.CreateDirectory(path);
+    Console.WriteLine($"This directory will be deleted in the finally block: '{dir.FullName}'");
+}
+finally
+{
+    fs.Directory.Delete(path, recursive: true);
+}
 ```
diff --git a/src/System.IO.Abstractions.Extensions/DisposableDirectory.cs b/src/System.IO.Abstractions.Extensions/DisposableDirectory.cs
@@ -0,0 +1,26 @@
+﻿namespace System.IO.Abstractions.Extensions
+{
+    /// <summary>
+    /// Creates a class that wraps a <see cref="IDirectoryInfo"/>. That wrapped directory will be
+    /// deleted when the <see cref="Dispose()"/> method is called.
+    /// </summary>
+    /// <inheritdoc/>
+    public class DisposableDirectory : DisposableFileSystemInfo<IDirectoryInfo>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DisposableDirectory"/> class.
+        /// </summary>
+        /// <param name="directoryInfo">
+        /// The directory to delete when this object is disposed.
+        /// </param>
+        public DisposableDirectory(IDirectoryInfo directoryInfo) : base(directoryInfo)
+        {
+        }
+
+        /// <inheritdoc/>
+        protected override void DeleteFileSystemInfo()
+        {
+            fileSystemInfo.Delete(recursive: true);
+        }
+    }
+}
diff --git a/src/System.IO.Abstractions.Extensions/DisposableFile.cs b/src/System.IO.Abstractions.Extensions/DisposableFile.cs
@@ -0,0 +1,20 @@
+﻿namespace System.IO.Abstractions.Extensions
+{
+    /// <summary>
+    /// Creates a class that wraps a <see cref="IFileInfo"/>. That wrapped file will be
+    /// deleted when the <see cref="Dispose()"/> method is called.
+    /// </summary>
+    /// <inheritdoc/>
+    public class DisposableFile : DisposableFileSystemInfo<IFileInfo>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DisposableFile"/> class.
+        /// </summary>
+        /// <param name="fileInfo">
+        /// The file to delete when this object is disposed.
+        /// </param>
+        public DisposableFile(IFileInfo fileInfo) : base(fileInfo)
+        {
+        }
+    }
+}
diff --git a/src/System.IO.Abstractions.Extensions/DisposableFileSystemInfo.cs b/src/System.IO.Abstractions.Extensions/DisposableFileSystemInfo.cs
@@ -0,0 +1,78 @@
+﻿namespace System.IO.Abstractions.Extensions
+{
+    /// <summary>
+    /// Creates a class that wraps a <see cref="IFileSystemInfo"/>. That wrapped object will be deleted
+    /// when the <see cref="Dispose()"/> method is called.
+    /// </summary>
+    /// <remarks>
+    /// This class is designed for the <c>using</c> pattern to ensure that a directory is
+    /// created and then deleted when it is no longer referenced. This is sometimes called
+    /// the RAII pattern (see https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization).
+    /// </remarks>
+    public class DisposableFileSystemInfo<T> : IDisposable where T : IFileSystemInfo
+    {
+        protected T fileSystemInfo;
+        private bool isDisposed;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DisposableFileSystemInfoBase"/> class.
+        /// </summary>
+        /// <param name="fileSystemInfo">
+        /// The directory to delete when this object is disposed.
+        /// </param>
+        public DisposableFileSystemInfo(T fileSystemInfo)
+        {
+            this.fileSystemInfo = fileSystemInfo ?? throw new ArgumentNullException(nameof(fileSystemInfo));
+
+            // Do an attribute refresh so that the object we return to the caller
+            // has up-to-date properties (like Exists).
+            this.fileSystemInfo.Refresh();
+        }
+
+        /// <summary>
+        /// Performs the actual work of releasing resources. This allows for subclasses to participate
+        /// in resource release.
+        /// </summary>
+        /// <param name="disposing">
+        /// <c>true</c> if if the call comes from a <see cref="Dispose()"/> method, <c>false</c> if it
+        /// comes from a finalizer.
+        /// </param>
+        protected virtual void Dispose(bool disposing)
+        {
+            if (!isDisposed)
+            {
+                if (disposing)
+                {
+                    DeleteFileSystemInfo();
+
+                    // Do an attribute refresh so that the object we returned to the
+                    // caller has up-to-date properties (like Exists).
+                    fileSystemInfo.Refresh();
+                }
+
+                isDisposed = true;
+            }
+        }
+
+        /// <inheritdoc/>
+        public void Dispose()
+        {
+            // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method.
+            // See https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-dispose.
+            Dispose(disposing: true);
+            GC.SuppressFinalize(this);
+        }
+
+        /// <summary>
+        /// Deletes the wrapped <typeparamref name="T"/> object.
+        /// </summary>
+        /// <remarks>
+        /// Different types of <typeparamref name="T"/> objects have different ways of deleting themselves (e.g.
+        /// directories usually need to be deleted recursively). This method is called by the <see cref="Dispose()"/>
+        /// </remarks>
+        protected virtual void DeleteFileSystemInfo()
+        {
+            fileSystemInfo.Delete();
+        }
+    }
+}
diff --git a/src/System.IO.Abstractions.Extensions/IFileSystemExtensions.cs b/src/System.IO.Abstractions.Extensions/IFileSystemExtensions.cs
@@ -1,4 +1,13 @@
-﻿namespace System.IO.Abstractions.Extensions
+﻿// S3874: "out" and "ref" parameters should not be used
+// https://rules.sonarsource.com/csharp/RSPEC-3874/
+//
+// Our CreateDisposableDirectory / CreateDisposableFile extensions
+// intentionally use an out param so that the DirectoryInfo / FileInfo
+// is passed out (similar to a Try* method) to the caller while the
+// returned object implements IDisposable to leverage the using statement.
+#pragma warning disable S3874
+
+namespace System.IO.Abstractions.Extensions
 {
     public static class IFileSystemExtensions
     {
@@ -11,5 +20,147 @@ public static IDirectoryInfo CurrentDirectory(this IFileSystem fileSystem)
         {
             return fileSystem.DirectoryInfo.New(fileSystem.Directory.GetCurrentDirectory());
         }
+
+        /// <summary>
+        /// Creates a new <see cref="IDirectoryInfo"/> using a random name from the temp path, and returns an <see cref="IDisposable"/>
+        /// that deletes the directory when disposed.
+        /// </summary>
+        /// <param name="fileSystem">
+        /// The <see cref="IFileSystem"/> in use.
+        /// </param>
+        /// <param name="directoryInfo">
+        /// The <see cref="IDirectoryInfo"/> for the directory that was created.
+        /// </param>
+        /// <returns>
+        /// An <see cref="IDisposable"/> to manage the directory's lifetime.
+        /// </returns>
+        public static IDisposable CreateDisposableDirectory(this IFileSystem fileSystem, out IDirectoryInfo directoryInfo)
+        {
+            return fileSystem.CreateDisposableDirectory(fileSystem.Path.GetRandomTempPath(), out directoryInfo);
+        }
+
+        /// <inheritdoc cref="CreateDisposableDirectory(IFileSystem, out IDirectoryInfo)"/>
+        /// <summary>
+        /// Creates a new <see cref="IDirectoryInfo"/> using a path provided by <paramref name="path"/>, and returns an
+        /// <see cref="IDisposable"/> that deletes the directory when disposed.
+        /// </summary>
+        /// <param name="path">
+        /// The full path to the directory to create.
+        /// </param>
+        /// <exception cref="ArgumentException">
+        /// If the directory already exists.
+        /// </exception>
+        public static IDisposable CreateDisposableDirectory(this IFileSystem fileSystem, string path, out IDirectoryInfo directoryInfo)
+        {
+            return fileSystem.CreateDisposableDirectory(path, dir => new DisposableDirectory(dir), out directoryInfo);
+        }
+
+        /// <inheritdoc cref="CreateDisposableDirectory(IFileSystem, string, out IDirectoryInfo)"/>
+        /// <summary>
+        /// Creates a new <see cref="IDirectoryInfo"/> using a path provided by <paramref name="path"/>, and returns an
+        /// <see cref="IDisposable"/> created by <paramref name="disposableFactory"/>, that should delete the directory when disposed.
+        /// </summary>
+        /// <param name="disposableFactory">
+        /// A <see cref="Func{T, TResult}"/> that acts as a factory method. Given the <see cref="IDirectoryInfo"/>, create the
+        /// <see cref="IDisposable"/> that will manage the its lifetime.
+        /// </param>
+        public static T CreateDisposableDirectory<T>(
+            this IFileSystem fileSystem,
+            string path,
+            Func<IDirectoryInfo, T> disposableFactory,
+            out IDirectoryInfo directoryInfo) where T : IDisposable
+        {
+            directoryInfo = fileSystem.DirectoryInfo.New(path);
+
+            if (directoryInfo.Exists)
+            {
+                throw CreateAlreadyExistsException(nameof(path), path);
+            }
+
+            directoryInfo.Create();
+
+            return disposableFactory(directoryInfo);
+        }
+
+        /// <summary>
+        /// Creates a new <see cref="IFileInfo"/> using a random name from the temp path, and returns an <see cref="IDisposable"/>
+        /// that deletes the file when disposed.
+        /// </summary>
+        /// <param name="fileSystem">
+        /// The <see cref="IFileSystem"/> in use.
+        /// </param>
+        /// <param name="fileInfo">
+        /// The <see cref="IFileInfo"/> for the file that was created.
+        /// </param>
+        /// <returns>
+        /// An <see cref="IDisposable"/> to manage the file's lifetime.
+        /// </returns>
+        public static IDisposable CreateDisposableFile(this IFileSystem fileSystem, out IFileInfo fileInfo)
+        {
+            return fileSystem.CreateDisposableFile(fileSystem.Path.GetRandomTempPath(), out fileInfo);
+        }
+
+        /// <inheritdoc cref="CreateDisposableFile(IFileSystem, out IFileInfo)"/>
+        /// <summary>
+        /// Creates a new <see cref="IFileInfo"/> using a path provided by <paramref name="path"/>, and returns an
+        /// <see cref="IDisposable"/> that deletes the file when disposed.
+        /// </summary>
+        /// <param name="path">
+        /// The full path to the file to create.
+        /// </param>
+        /// <exception cref="ArgumentException">
+        /// If the file already exists.
+        /// </exception>
+        public static IDisposable CreateDisposableFile(this IFileSystem fileSystem, string path, out IFileInfo fileInfo)
+        {
+            return fileSystem.CreateDisposableFile(path, file => new DisposableFile(file), out fileInfo);
+        }
+
+        /// <inheritdoc cref="CreateDisposableFile(IFileSystem, string, out IFileInfo)"/>
+        /// <summary>
+        /// Creates a new <see cref="IFileInfo"/> using a path provided by <paramref name="path"/>, and returns an
+        /// <see cref="IDisposable"/> created by <paramref name="disposableFactory"/>, that should delete the file when disposed.
+        /// </summary>
+        /// <param name="disposableFactory">
+        /// A <see cref="Func{T, TResult}"/> that acts as a factory method. Given the <see cref="IFileInfo"/>, create the
+        /// <see cref="IDisposable"/> that will manage the its lifetime.
+        /// </param>
+        public static T CreateDisposableFile<T>(
+            this IFileSystem fileSystem,
+            string path,
+            Func<IFileInfo, T> disposableFactory,
+            out IFileInfo fileInfo) where T : IDisposable
+        {
+            fileInfo = fileSystem.FileInfo.New(path);
+
+            if (fileInfo.Exists)
+            {
+                throw CreateAlreadyExistsException(nameof(path), path);
+            }
+
+            // Ensure we close the handle to the file after we create it, otherwise
+            // callers may get an access denied error.
+            fileInfo.Create().Dispose();
+
+            return disposableFactory(fileInfo);
+        }
+
+        private static string GetRandomTempPath(this IPath path)
+        {
+            var temp = path.GetTempPath();
+            var fileName = path.GetRandomFileName();
+            return path.Combine(temp, fileName);
+        }
+
+        private static ArgumentException CreateAlreadyExistsException(string argumentName, string path)
+        {
+            // Having the colliding path availabe as part of the exception is very useful for debugging.
+            // However, paths can be considered sensitive information in some contexts (like web servers).
+            // Thus, we add the path to the exception's data , rather than the message.
+            var ex = new ArgumentException("File already exists", argumentName);
+            ex.Data.Add("path", path);
+
+            return ex;
+        }
     }
 }
diff --git a/tests/System.IO.Abstractions.Extensions.Tests/DisposableDirectoryTests.cs b/tests/System.IO.Abstractions.Extensions.Tests/DisposableDirectoryTests.cs
@@ -0,0 +1,41 @@
+﻿using NUnit.Framework;
+
+namespace System.IO.Abstractions.Extensions.Tests
+{
+    [TestFixture]
+    public class DisposableDirectoryTests
+    {
+        [Test]
+        public void DisposableDirectory_Throws_ArgumentNullException_For_Null_IDirectoryInfo_Test()
+        {
+            Assert.Throws<ArgumentNullException>(() => new DisposableDirectory(null!));
+        }
+
+        [Test]
+        public void DisposableDirectory_DeleteRecursive_On_Dispose_Test()
+        {
+            // Arrange
+            var fs = new FileSystem();
+            var path = fs.Path.Combine(fs.Directory.GetCurrentDirectory(), fs.Path.GetRandomFileName());
+            var dirInfo = fs.DirectoryInfo.New(path);
+
+            // Create a subdirectory to ensure recursive delete
+            dirInfo.CreateSubdirectory(Guid.NewGuid().ToString());
+
+            // Assert directory exists
+            Assert.IsTrue(fs.Directory.Exists(path), "Directory should exist");
+            Assert.IsTrue(dirInfo.Exists, "IDirectoryInfo.Exists should be true");
+
+            // Act
+            var disposableDirectory = new DisposableDirectory(dirInfo);
+            disposableDirectory.Dispose();
+
+            // Assert directory is deleted
+            Assert.IsFalse(fs.Directory.Exists(path), "Directory should not exist");
+            Assert.IsFalse(dirInfo.Exists, "IDirectoryInfo.Exists should be false");
+
+            // Assert a second dispose does not throw
+            Assert.DoesNotThrow(() => disposableDirectory.Dispose());
+        }
+    }
+}
diff --git a/tests/System.IO.Abstractions.Extensions.Tests/DisposableFileTests.cs b/tests/System.IO.Abstractions.Extensions.Tests/DisposableFileTests.cs
diff --git a/tests/System.IO.Abstractions.Extensions.Tests/FileSystemExtensionsTests.cs b/tests/System.IO.Abstractions.Extensions.Tests/FileSystemExtensionsTests.cs
