Add troubleshooting guidance for SQL Encrypt breaking change

menu/menu.yaml

@@ -891,6 +891,8 @@
       Title: Callback support
     - Url: transports/sql/sql-azure
       Title: Azure SQL considerations
+    - Url: transports/sql/troubleshooting
+      Title: Troubleshooting
   - Url: transports/msmq
     Title: MSMQ
     Articles:
@@ -1109,6 +1111,8 @@
       Title: Installer Workflow
     - Url: persistence/sql/migrating-from-nhibernate
       Title: Migrating from NHibernate
+    - Url: persistence/sql/troubleshooting
+      Title: Troubleshooting
   - Title: Cosmos DB
     Url: persistence/cosmosdb
     Articles:

persistence/sql/troubleshooting.md

@@ -0,0 +1,27 @@
+---
+title: SQL Persistence Troubleshooting
+summary: Tips on what to do when the SQL Persistence is not behaving as expected
+component: SQLPersistence
+reviewed: 2022-03-24
+related:
+ - persistence/sql
+---
+
+## SqlException: certificate chain not trusted
+
+After upgrading to version 4 of the `Microsoft.Data.SqlClient` package the endpoint may throw the following error at startup:
+
+```
+System.Data.SqlClient.SqlException
+  HResult=0x80131904
+  Message=A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
+  Source=.Net SqlClient Data Provider
+```
+
+SQL Server uses a certificate to encrypt communication between itself and endpoints. Version 4 of the `Microsoft.Data.SqlClient` package includes a [breaking change](https://github.com/dotnet/SqlClient/pull/1210) to set `Encrypt=true` by default (the previous default was `false`) which causes this exception.
+
+To fix it, [the SQL Server installation must be updated with a valid certificate and the client machine must be updated to trust this certificate](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine).
+
+WARNING: It is not recommended to eliminate this warning by adding `Encrypt=False` or `TrustServerCertificate=True` to the connection string. Both of these options leave the endpoint unsecure.
+
+NOTE: If the endpoint connection string already contains `Encrypt=true` it may be removed.

servicecontrol/troubleshooting.md

@@ -65,6 +65,23 @@ If ServiceControl fails to start and the logs contain a `Microsoft.Isam.Esent.In
  1. Run `esentutl /p Data` and wait for it to finish
  1. Restart ServiceControl
 
+## Service fails to start: SqlException certificate chain not trusted
+
+If ServiceControl fails to start and the logs contain the following exception, then ServiceControl is not able to connect to the SQL Server instance.  
+
+```
+System.Data.SqlClient.SqlException
+  HResult=0x80131904
+  Message=A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
+  Source=.Net SqlClient Data Provider
+```
+
+SQL Server uses a certificate to encrypt communication between itself and ServiceControl. Version 4 of the `Microsoft.Data.SqlClient` package includes a [breaking change](https://github.com/dotnet/SqlClient/pull/1210) to set `Encrypt=true` by default (the previous default was `false`) which causes this exception.
+
+To fix it, [the SQL Server installation must be updated with a valid certificate and the ServiceControl machine must be updated to trust this certificate](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine).
+
+WARNING: It is not recommended to eliminate this warning by adding `Encrypt=False` or `TrustServerCertificate=True` to the connection string. Both of these options leave the ServiceControl installation unsecure.
+
 ## Unable to connect to ServiceControl from either ServiceInsight or ServicePulse
 
  1. Log on to the machine hosting ServiceControl.

transports/sql/troubleshooting.md

@@ -0,0 +1,27 @@
+---
+title: SQL Transport Troubleshooting
+summary: Tips on what to do when the SQL Transport is not behaving as expected
+component: SQLTransport
+reviewed: 2022-03-24
+related:
+ - transports/sql
+---
+
+## SqlException: certificate chain not trusted
+
+After upgrading to version 4 of the `Microsoft.Data.SqlClient` package the endpoint may throw the following error at startup:
+
+```
+System.Data.SqlClient.SqlException
+  HResult=0x80131904
+  Message=A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
+  Source=.Net SqlClient Data Provider
+```
+
+SQL Server uses a certificate to encrypt communication between itself and endpoints. Version 4 of the `Microsoft.Data.SqlClient` package includes a [breaking change](https://github.com/dotnet/SqlClient/pull/1210) to set `Encrypt=true` by default (the previous default was `false`) which causes this exception.
+
+To fix it, [the SQL Server installation must be updated with a valid certificate and the client machine must be updated to trust this certificate](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine).
+
+WARNING: It is not recommended to eliminate this warning by adding `Encrypt=False` or `TrustServerCertificate=True` to the connection string. Both of these options leave the endpoint unsecure.
+
+NOTE: If the endpoint connection string already contains `Encrypt=true` it may be removed.

transports/upgrades/sqlserver-5to6.md

@@ -26,6 +26,8 @@ The new NServiceBus.Transport.SqlServer package references `Microsoft.Data.SqlCl
 
 NOTE: `System.Data.SqlClient` is in maintenance mode. Microsoft will bring new features and improvements to [`Microsoft.Data.SqlClient`](https://www.nuget.org/packages/Microsoft.Data.SqlClient/) only. For more information, read [Introduction to the new Microsoft.Data.SqlClient](https://devblogs.microsoft.com/dotnet/introducing-the-new-microsoftdatasqlclient/). It is recommended to switch to the new client if possible.
 
+include: sqlserver-client4breakingchange
+
 ## Moved types from namespace `NServiceBus.Transport.SQLServer` to `NServiceBus.Transport.SqlServer`
 
 Certain advanced configuration APIs have been moved from the namespace `NServiceBus.Transport.SQLServer` to `NServiceBus.Transport.SqlServer` (note the change in case). Code must to be adjusted accordingly. A straight forward way is to search and replace

transports/upgrades/sqlserver-6to7.md

@@ -32,6 +32,8 @@ endpointConfiguration.UseTransport(transport);
 
 include: v7-usetransport-shim-api
 
+include: sqlserver-client4breakingchange
+
 ## Configuration options
 
 The SQL Server transport configuration options have moved to the `SqlServerTransport` class. See the following table for further information:

transports/upgrades/sqlserver-client4breakingchange.include.md

@@ -0,0 +1,14 @@
+### `Microsoft.Data.SqlClient` version 4 and above
+
+Version 4 of `Microsoft.Data.SqlClient` includes [a breaking change](https://github.com/dotnet/SqlClient/pull/1210) which sets `Encrypt=True` by default. If the client and server are not configured with a valid certificate, this can cause an exception at startup:
+
+```
+System.Data.SqlClient.SqlException
+  HResult=0x80131904
+  Message=A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
+  Source=.Net SqlClient Data Provider
+```
+
+To fix this, [the SQL Server installation must be updated with a valid certificate and the machine hosting the endpoint must be updated to trust this certificate](https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-encrypted-connections-to-the-database-engine).
+
+WARNING: It is not recommended to eliminate this warning by adding `Encrypt=False` or `TrustServerCertificate=True` to the connection string. Both of these options leave the endpoint unsecure.