Merge pull request #4 from CodeDead/release/v1.0.1

Release/v1.0.1

Author: CodeDead

README.md

@@ -5,15 +5,30 @@
 ![GitHub](https://img.shields.io/badge/language-C%23-green)
 ![GitHub](https://img.shields.io/github/license/CodeDead/deadlock-dotnet-sdk)
 
-deadlock-dotnet-sdk is a simple-to-use SDK for unlocking files in C# / dotnet.
+deadlock-dotnet-sdk is a simple-to-use SDK for unlocking files in C# / dotnet on Windows based operating systems.
 
 ## Usage
 
-Add deadlock-dotnet-sdk to your solution tree using NuGet:
+Add deadlock-dotnet-sdk to your solution tree using [NuGet](https://www.nuget.org/packages/deadlock-dotnet-sdk/):
 ```shell
 Install-Package deadlock-dotnet-sdk
 ```
 
+You can initialize a new `DeadLock` helper object like so:
+```c#
+DeadLock deadLock = new DeadLock();
+```
+
+In addition, if you would like to rethrow inner exceptions, you can change the `RethrowExceptions` property when declaring a new `DeadLock` object:
+```c#
+DeadLock deadLock = new DeadLock(`true` | `false`);
+```
+
+You can also change the property dynamically:
+```c#
+deadlock.RethrowExceptions = `true` | `false`
+```
+
 ### Finding the processes that are locking a file
 
 To find all the `FileLocker` objects that are locking a file, you can make use of the `FindLockingProcesses` method:
@@ -28,6 +43,11 @@ string path = @"C:\...\file.txt";
 List<FileLocker> lockers = await DeadLock.FindLockingProcessesAsync(path);
 ```
 
+To find the `Process` objects that are locking one or more files, you can invoke the `FindLockingProcesses` (or `FindLockingProcessesAsync`) method with multiple `path` parameters:
+```c#
+List<FileLocker> fileLockers = FindLockingProcesses("a", "c", "c");
+```
+
 ### Unlocking a file
 
 To unlock a `FileLocker`, you can execute the  `Unlock` method:
@@ -37,12 +57,71 @@ DeadLock.Unlock(locker);
 
 You can also run the code asynchronously by running the `UnlockAsync` method:
 ```c#
-DeadLock.UnlockAsync(locker);
+await DeadLock.UnlockAsync(locker);
+```
+
+To unlock more than one `FileLocker` object, you can invoke the `Unlock` (or `UnlockAsync`) method with multiple `FileLocker` parameters:
+```c#
+Unlock(fileLockerA, fileLockerB, fileLockerC);
 ```
 
+Alternatively, if you only want to unlock a file and you are not interested in using the `FileLocker` objects, you can do so by providing any of the `Unlock` or `UnlockAsync` methods with one or more `string` variables that represent the path or paths of the file(s) that should be unlocked:
+```c#
+// Unlock a single path
+string path = @"C:\...\file.txt"; 
+Unlock(path);
+
+// Unlock multiple files
+Unlock(path1, path2, path3);
+
+// Asynchronously unlock one or more files
+await UnlockAsync(path);
+await UnlockAsync(path1, path2, path3);
+```
+
+### `FileLocker`
+
+The `FileLocker` object contains a `List` of `System.Diagnostics.Process` objects that are locking a file.
+You can retrieve the `List` of `Process` objects by retrieving the respective property:
+```c#
+List<Process> processes = fileLocker.Lockers;
+```
+
+To retrieve the path of the file that the `Process` objects are locking, you can make use of the `Path` property:
+```c#
+string path = fileLocker.Path;
+```
+
+### Error handling
+
+deadlock-dotnet-sdk has three specific `Exception` types that might occur when trying to find the `Process` objects that are locking a file.
+
+* `RegisterResourceException`
+* `RmListException`
+* `StartSessionException`
+
+In case you want more detailed error messages, it is recommended that you call the `Marshal.GetLastWin32Error` method as soon as one of these `Exception` types occur:  
+https://docs.microsoft.com/en-us/dotnet/api/system.runtime.interopservices.marshal.getlastwin32error?view=net-6.0
+
+#### `RegisterResourceException`
+
+This error occurs when the system goes out of memory, when a specific time-out occurs or if an invalid handle is detected. You can find more information about this exception here:  
+https://docs.microsoft.com/en-us/windows/win32/api/restartmanager/nf-restartmanager-rmregisterresources#return-value
+
+#### `RmListException`
+
+This error occurs when the system goes out of memory, when a specific time-out occurs or if an invalid handle is detected. You can find more information about this exception here:  
+https://docs.microsoft.com/en-us/windows/win32/api/restartmanager/nf-restartmanager-rmgetlist#return-value
+
+#### `StartSessionException`
+
+This error occurs when the system goes out of memory, when a specific time-out occurs or if an invalid handle is detected. You can find more information about this exception here:  
+https://docs.microsoft.com/en-us/windows/win32/api/restartmanager/nf-restartmanager-rmstartsession#return-value
+
 ## Credits
 
-Images by: [RemixIcon](https://remixicon.com/)
+* [RemixIcon](https://remixicon.com/)
+* [dotnet](https://dotnet.microsoft.com/en-us/)
 
 ## About
 

deadlock-dotnet-sdk/DeadLock.cs

@@ -5,16 +5,41 @@ namespace deadlock_dotnet_sdk
 {
     public class DeadLock
     {
+        #region Properties
+
+        /// <summary>
+        /// Property that specifies whether inner exceptions should be rethrown or not
+        /// </summary>
+        public bool RethrowExceptions { get; set; }
+
+        #endregion
+
+        /// <summary>
+        /// Default constructor
+        /// </summary>
+        public DeadLock()
+        {
+            // Default constructor
+        }
+
+        /// <summary>
+        /// Initialize a new DeadLock
+        /// </summary>
+        /// <param name="rethrowExceptions">True if inner exceptions should be rethrown, otherwise false</param>
+        public DeadLock(bool rethrowExceptions)
+        {
+            RethrowExceptions = rethrowExceptions;
+        }
+
         /// <summary>
         /// Retrieve the FileLocker object that contains a List of Process objects that are locking a file
         /// </summary>
         /// <param name="filePath">The full path of a file</param>
         /// <returns>The FileLocker object that contains a List of Process objects that are locking a file</returns>
         public FileLocker FindLockingProcesses(string filePath)
         {
-            IEnumerable<Process> lockers = NativeMethods.FindLockingProcesses(filePath);
-            FileLocker fileLocker = new(filePath, lockers.ToList());
-
+            FileLocker fileLocker = new(filePath,
+                NativeMethods.FindLockingProcesses(filePath, RethrowExceptions).ToList());
             return fileLocker;
         }
 
@@ -45,8 +70,8 @@ public async Task<FileLocker> FindLockingProcessesAsync(string filePath)
 
             await Task.Run(() =>
             {
-                IEnumerable<Process> lockers = NativeMethods.FindLockingProcesses(filePath);
-                fileLocker = new(filePath, lockers.ToList());
+                fileLocker = new FileLocker(filePath,
+                    NativeMethods.FindLockingProcesses(filePath, RethrowExceptions).ToList());
             });
 
             return fileLocker;
@@ -57,16 +82,16 @@ await Task.Run(() =>
         /// </summary>
         /// <param name="filePaths">The full path of a file</param>
         /// <returns>The List of FileLocker objects that contain the processes that are locking a file</returns>
-        public async Task<List<FileLocker>> FindLockingProcessesAsnyc(params string[] filePaths)
+        public async Task<List<FileLocker>> FindLockingProcessesAsync(params string[] filePaths)
         {
             List<FileLocker> fileLockers = new();
 
             await Task.Run(() =>
             {
                 foreach (string filePath in filePaths)
                 {
-                    IEnumerable<Process> lockers = NativeMethods.FindLockingProcesses(filePath);
-                    fileLockers.Add(new(filePath, lockers.ToList()));
+                    fileLockers.Add(new FileLocker(filePath,
+                        NativeMethods.FindLockingProcesses(filePath, RethrowExceptions).ToList()));
                 }
             });
 
@@ -103,7 +128,7 @@ public void Unlock(params FileLocker[] fileLockers)
         /// Unlock a File asynchronously by killing all the processes that are holding a handle on the file
         /// </summary>
         /// <param name="fileLocker">The FileLocker that contains the List of Process objects that should be killed</param>
-        public async void UnlockAsync(FileLocker fileLocker)
+        public async Task UnlockAsync(FileLocker fileLocker)
         {
             await Task.Run(() =>
             {
@@ -120,7 +145,7 @@ await Task.Run(() =>
         /// Unlock one or more files asynchronously by killing all the processes that are holding a handle on the files 
         /// </summary>
         /// <param name="fileLockers">The FileLocker objects that contain the List of Process objects that are locking a file</param>
-        public async void UnlockAsync(params FileLocker[] fileLockers)
+        public async Task UnlockAsync(params FileLocker[] fileLockers)
         {
             await Task.Run(() =>
             {
@@ -135,5 +160,52 @@ await Task.Run(() =>
                 }
             });
         }
+
+        /// <summary>
+        /// Unlock a file without retrieving the List of FileLocker objects
+        /// </summary>
+        /// <param name="filePath">The path of the file that should be unlocked</param>
+        public void Unlock(string filePath)
+        {
+            FileLocker fileLocker = FindLockingProcesses(filePath);
+            Unlock(fileLocker);
+        }
+
+        /// <summary>
+        /// Unlock a file without retrieving the List of FileLocker objects asynchronously
+        /// </summary>
+        /// <param name="filePath">The path of the file that should be unlocked</param>
+        public async Task UnlockAsync(string filePath)
+        {
+            FileLocker locker = await FindLockingProcessesAsync(filePath);
+            await UnlockAsync(locker);
+        }
+
+        /// <summary>
+        /// Unlock one or more files without retrieving the List of FileLocker objects
+        /// </summary>
+        /// <param name="filePaths">The full paths of the files that should be unlocked</param>
+        public void Unlock(params string[] filePaths)
+        {
+            List<FileLocker> fileLockers = FindLockingProcesses(filePaths);
+
+            foreach (FileLocker fileLocker in fileLockers)
+            {
+                Unlock(fileLocker);
+            }
+        }
+
+        /// <summary>
+        /// Unlock one or more files without retrieving the List of FileLocker objects asynchronously
+        /// </summary>
+        /// <param name="filePaths">The full paths of the files that should be unlocked</param>
+        public async Task UnlockAsync(params string[] filePaths)
+        {
+            List<FileLocker> fileLockers = await FindLockingProcessesAsync(filePaths);
+            foreach (FileLocker f in fileLockers)
+            {
+                await UnlockAsync(f);
+            }
+        }
     }
 }

deadlock-dotnet-sdk/Domain/FileLocker.cs

@@ -7,14 +7,14 @@ public class FileLocker
         #region Properties
 
         /// <summary>
-        /// Get the path of the file that is locked
+        /// Get or set the path of the file that is locked
         /// </summary>
-        public string Path { get; }
+        public string Path { get; set; }
 
         /// <summary>
-        /// Get the List of Process objects that are locking the file
+        /// Get or set the List of Process objects that are locking the file
         /// </summary>
-        public List<Process> Lockers { get; }
+        public List<Process> Lockers { get; set; }
 
         #endregion