Provide options to control shutdown

pages/directory-and-name-resolution.md

@@ -113,7 +113,7 @@ public Task<SqlDatabase> Build(
         string? databaseSuffix = null,
         [CallerMemberName] string memberName = "")
 ```
-<sup><a href='/src/LocalDb/SqlInstance.cs#L120-L142' title='Snippet source file'>snippet source</a> | <a href='#snippet-conventionbuildsignature' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/LocalDb/SqlInstance.cs#L132-L154' title='Snippet source file'>snippet source</a> | <a href='#snippet-conventionbuildsignature' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 With these parameters the database name is the derived as follows:
@@ -150,7 +150,7 @@ If full control over the database name is required, there is an overload that ta
 /// </summary>
 public async Task<SqlDatabase> Build(string dbName)
 ```
-<sup><a href='/src/LocalDb/SqlInstance.cs#L157-L164' title='Snippet source file'>snippet source</a> | <a href='#snippet-explicitbuildsignature' title='Start of snippet'>anchor</a></sup>
+<sup><a href='/src/LocalDb/SqlInstance.cs#L169-L176' title='Snippet source file'>snippet source</a> | <a href='#snippet-explicitbuildsignature' title='Start of snippet'>anchor</a></sup>
 <!-- endSnippet -->
 
 Which can be used as follows:

src/EfClassicLocalDb/EfClassicLocalDb.csproj

@@ -25,6 +25,7 @@
     <Compile Include="..\LocalDb\LocalDbInstanceInfo.cs" />
     <Compile Include="..\LocalDb\LocalDbApi.cs" />
     <Compile Include="..\LocalDb\MethodTimeLogger.cs" />
+    <Compile Include="..\LocalDb\ShutdownMode.cs" />
     <Compile Include="..\LocalDb\SqlExtensions.cs" />
     <Compile Include="..\LocalDb\Wrapper.cs" />
     <Compile Include="..\LocalDb\State.cs" />

src/EfClassicLocalDb/SqlInstance.cs

@@ -97,7 +97,23 @@ static DateTime GetTimestamp(DateTime? timestamp, Delegate? buildTemplate)
         return Timestamp.LastModified<TDbContext>();
     }
 
-    public void Cleanup() => Wrapper.DeleteInstance();
+    public void Cleanup()
+    {
+        Guard.AgainstBadOS();
+        Wrapper.DeleteInstance();
+    }
+
+    public void Cleanup(ShutdownMode shutdownMode)
+    {
+        Guard.AgainstBadOS();
+        Wrapper.DeleteInstance(shutdownMode);
+    }
+
+    public void Cleanup(ShutdownMode shutdownMode, TimeSpan timeout)
+    {
+        Guard.AgainstBadOS();
+        Wrapper.DeleteInstance(shutdownMode, timeout);
+    }
 
     Task<string> BuildDatabase(string dbName) => Wrapper.CreateDatabaseFromTemplate(dbName);
 

src/EfLocalDb/EfLocalDb.csproj

@@ -24,6 +24,7 @@
     <Compile Include="..\LocalDb\LocalDbInstanceInfo.cs" />
     <Compile Include="..\LocalDb\LocalDbApi.cs" />
     <Compile Include="..\LocalDb\MethodTimeLogger.cs" />
+    <Compile Include="..\LocalDb\ShutdownMode.cs" />
     <Compile Include="..\LocalDb\SqlExtensions.cs" />
     <Compile Include="..\LocalDb\Wrapper.cs" />
     <Compile Include="..\LocalDb\State.cs" />

src/LocalDb/LocalDbApi.cs

@@ -1,6 +1,12 @@
 using System.ComponentModel;
 using System.Runtime.InteropServices;
 
+#if EF
+using EfLocalDb;
+#else
+using LocalDb;
+#endif
+
 static class LocalDbApi
 {
     static IntPtr api;
@@ -125,9 +131,14 @@ public static LocalDbInstanceInfo GetInstance(string instanceName)
 
     public static void DeleteInstance(string instanceName) => deleteInstance(instanceName, 0);
 
-    public static void StopAndDelete(string instanceName)
+    private static readonly TimeSpan DefaultShutdownTimeout = TimeSpan.FromSeconds(10);
+
+    public static void StopAndDelete(string instanceName, ShutdownMode shutdownMode = ShutdownMode.KillProcess) =>
+        StopAndDelete(instanceName, shutdownMode, DefaultShutdownTimeout);
+
+    public static void StopAndDelete(string instanceName, ShutdownMode shutdownMode, TimeSpan timeout)
     {
-        StopInstance(instanceName);
+        StopInstance(instanceName, shutdownMode, timeout);
         DeleteInstance(instanceName);
     }
 
@@ -160,5 +171,9 @@ public static void StartInstance(string instanceName)
         startInstance(instanceName, 0, connection, ref size);
     }
 
-    public static void StopInstance(string instanceName) => stopInstance(instanceName, 0, 10000);
+    public static void StopInstance(string instanceName, ShutdownMode shutdownMode = ShutdownMode.UseSqlShutdown) =>
+        StopInstance(instanceName, shutdownMode, DefaultShutdownTimeout);
+
+    public static void StopInstance(string instanceName, ShutdownMode shutdownMode, TimeSpan timeout) =>
+        stopInstance(instanceName, (int)shutdownMode, (int)timeout.TotalMilliseconds);
 }

src/LocalDb/ShutdownMode.cs

@@ -0,0 +1,32 @@
+#if EF
+namespace EfLocalDb;
+#else
+namespace LocalDb;
+#endif
+
+/// <summary>
+/// Provides options for how to shut down the instance.
+/// </summary>
+/// <remarks>
+/// See https://docs.microsoft.com/sql/relational-databases/express-localdb-instance-apis/localdbstopinstance-function
+/// </remarks>
+public enum ShutdownMode
+{
+    /// <summary>
+    /// Shutdown cleanly, using the <c>SHUTDOWN</c> T-SQL command.
+    /// See https://docs.microsoft.com/sql/t-sql/language-elements/shutdown-transact-sql
+    /// </summary>
+    UseSqlShutdown = 0,
+
+    /// <summary>
+    /// Shutdown immediately, by asking the operating system to kill the process hosting the instance.
+    /// The database may be corrupted by this approach, so only use when you intend to delete the instance.
+    /// </summary>
+    KillProcess = 1,
+
+    /// <summary>
+    /// Shutdown using the <c>SHUTDOWN WITH NOWAIT</c> T-SQL command, which does not perform checkpoints in the database.
+    /// See https://docs.microsoft.com/sql/t-sql/language-elements/shutdown-transact-sql
+    /// </summary>
+    UseSqlShutdownWithNoWait = 2
+}

src/LocalDb/SqlInstance.cs

@@ -115,6 +115,18 @@ public void Cleanup()
         Wrapper.DeleteInstance();
     }
 
+    public void Cleanup(ShutdownMode shutdownMode)
+    {
+        Guard.AgainstBadOS();
+        Wrapper.DeleteInstance(shutdownMode);
+    }
+
+    public void Cleanup(ShutdownMode shutdownMode, TimeSpan timeout)
+    {
+        Guard.AgainstBadOS();
+        Wrapper.DeleteInstance(shutdownMode, timeout);
+    }
+
     Task<string> BuildContext(string dbName) => Wrapper.CreateDatabaseFromTemplate(dbName);
 
     #region ConventionBuildSignature

src/LocalDb/Wrapper.cs

@@ -261,9 +261,16 @@ async Task Rebuild(DateTime timestamp, Func<DbConnection, Task> buildTemplate, D
     }
 
     [Time]
-    public void DeleteInstance()
+    public void DeleteInstance(ShutdownMode shutdownMode = ShutdownMode.KillProcess)
     {
-        LocalDbApi.StopAndDelete(instance);
+        LocalDbApi.StopAndDelete(instance, shutdownMode);
+        System.IO.Directory.Delete(Directory, true);
+    }
+
+    [Time]
+    public void DeleteInstance(ShutdownMode shutdownMode, TimeSpan timeout)
+    {
+        LocalDbApi.StopAndDelete(instance, shutdownMode, timeout);
         System.IO.Directory.Delete(Directory, true);
     }