Add troubleshooting guidance for SQL Encrypt breaking change

menu/menu.yaml

@@ -714,6 +714,8 @@
         Title: Version 3 to 4
     - Title: SQL Server
       Articles:
+      - Url: transports/upgrades/sqlserver-client4
+        Title: Microsoft.Data.SqlClient version 4
       - Url: transports/upgrades/sqlserver-6to7
         Title: Version 6 to 7
       - Url: transports/upgrades/sqlserver-non-clustered-idx
@@ -891,6 +893,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:
@@ -1031,6 +1035,8 @@
         Title: Version 3 to 4
     - Title: SQL
       Articles:
+      - Url: persistence/upgrades/sql-client4
+        Title: Microsoft.Data.SqlClient version 4
       - Url: persistence/upgrades/sql-6to7
         Title: Version 6 to 7
       - Url: persistence/upgrades/sql-5to6
@@ -1109,6 +1115,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,12 @@
+---
+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
+
+include: sql-client4

persistence/upgrades/sql-client4.include.md

@@ -0,0 +1,12 @@
+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.

persistence/upgrades/sql-client4.md

@@ -0,0 +1,11 @@
+---
+title: SQL Server Persistence Upgrade - SqlClient version 4
+summary: How to update to Microsoft.Data.SqlClient version 4
+component: SqlPersistence
+reviewed: 2022-03-25
+isUpgradeGuide: true
+related:
+- transports/upgrades/sqlserver-client4
+---
+
+include: sql-client4

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
+```
+
+When encyrption is enabled, 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,12 @@
+---
+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
+
+include: sql-client4

transports/upgrades/sqlserver-client4.md

@@ -0,0 +1,11 @@
+---
+title: SQL Server Transport Upgrade - SqlClient version 4
+summary: How to update to Microsoft.Data.SqlClient version 4
+component: SqlTransport
+reviewed: 2022-03-25
+isUpgradeGuide: true
+related:
+- persistence/upgrades/sql-client4
+---
+
+include: sql-client4