From 9011568111f90464a33b829d7e45e8896d45fa97 Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Thu, 24 Mar 2022 13:19:44 +0800 Subject: [PATCH 1/7] Add guidance for SQL-P --- menu/menu.yaml | 2 ++ persistence/sql/troubleshooting.md | 27 +++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 persistence/sql/troubleshooting.md diff --git a/menu/menu.yaml b/menu/menu.yaml index b9cd98fc9ad..9f8e0e90454 100644 --- a/menu/menu.yaml +++ b/menu/menu.yaml @@ -1109,6 +1109,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: diff --git a/persistence/sql/troubleshooting.md b/persistence/sql/troubleshooting.md new file mode 100644 index 00000000000..53026803c1f --- /dev/null +++ b/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. \ No newline at end of file From 7b63af8812f98b1ea701bb064be398bb2c26d9aa Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Thu, 24 Mar 2022 14:06:21 +0800 Subject: [PATCH 2/7] Add guidance for SQL-T --- menu/menu.yaml | 2 ++ transports/sql/troubleshooting.md | 27 +++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) create mode 100644 transports/sql/troubleshooting.md diff --git a/menu/menu.yaml b/menu/menu.yaml index 9f8e0e90454..4d6120afa2c 100644 --- a/menu/menu.yaml +++ b/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: diff --git a/transports/sql/troubleshooting.md b/transports/sql/troubleshooting.md new file mode 100644 index 00000000000..9c945a78158 --- /dev/null +++ b/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: + - transport/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. \ No newline at end of file From 57ccb47d2a429659e5bc03185a59ee6309741fbf Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Thu, 24 Mar 2022 14:13:20 +0800 Subject: [PATCH 3/7] Fix link --- transports/sql/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/transports/sql/troubleshooting.md b/transports/sql/troubleshooting.md index 9c945a78158..ce8f2de009a 100644 --- a/transports/sql/troubleshooting.md +++ b/transports/sql/troubleshooting.md @@ -4,7 +4,7 @@ summary: Tips on what to do when the SQL Transport is not behaving as expected component: SQLTransport reviewed: 2022-03-24 related: - - transport/sql + - transports/sql --- ## SqlException: certificate chain not trusted From 787417a524df6fdc8c90a277e789cdd30cdb505b Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Thu, 24 Mar 2022 15:15:43 +0800 Subject: [PATCH 4/7] Add troubleshooting info for ServiceControl --- servicecontrol/troubleshooting.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/servicecontrol/troubleshooting.md b/servicecontrol/troubleshooting.md index cee5622c2e7..6fd42b687fc 100644 --- a/servicecontrol/troubleshooting.md +++ b/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. From e53a74d2c11f9e4679529b51f106ae1847b63245 Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Thu, 24 Mar 2022 15:27:41 +0800 Subject: [PATCH 5/7] SQL-T upgrade guide --- transports/upgrades/sqlserver-5to6.md | 2 ++ transports/upgrades/sqlserver-6to7.md | 2 ++ .../sqlserver-client4breakingchange.include.md | 14 ++++++++++++++ 3 files changed, 18 insertions(+) create mode 100644 transports/upgrades/sqlserver-client4breakingchange.include.md diff --git a/transports/upgrades/sqlserver-5to6.md b/transports/upgrades/sqlserver-5to6.md index f480240429f..c575d23af5c 100644 --- a/transports/upgrades/sqlserver-5to6.md +++ b/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 diff --git a/transports/upgrades/sqlserver-6to7.md b/transports/upgrades/sqlserver-6to7.md index 148fc1a69a8..ddd1520e30e 100644 --- a/transports/upgrades/sqlserver-6to7.md +++ b/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: diff --git a/transports/upgrades/sqlserver-client4breakingchange.include.md b/transports/upgrades/sqlserver-client4breakingchange.include.md new file mode 100644 index 00000000000..182f2c6145c --- /dev/null +++ b/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. \ No newline at end of file From 4f4c88c1f90414ddcc11e3dba0ce5dac6206f846 Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Fri, 25 Mar 2022 14:31:54 +0800 Subject: [PATCH 6/7] Include standalone upgrade guides and remove duplication --- menu/menu.yaml | 4 ++++ persistence/sql/troubleshooting.md | 17 +---------------- .../upgrades/sql-client4.include.md | 2 -- persistence/upgrades/sql-client4.md | 11 +++++++++++ transports/sql/troubleshooting.md | 17 +---------------- transports/upgrades/sqlserver-5to6.md | 2 -- transports/upgrades/sqlserver-6to7.md | 2 -- transports/upgrades/sqlserver-client4.md | 11 +++++++++++ 8 files changed, 28 insertions(+), 38 deletions(-) rename transports/upgrades/sqlserver-client4breakingchange.include.md => persistence/upgrades/sql-client4.include.md (95%) create mode 100644 persistence/upgrades/sql-client4.md create mode 100644 transports/upgrades/sqlserver-client4.md diff --git a/menu/menu.yaml b/menu/menu.yaml index 4d6120afa2c..963938133e7 100644 --- a/menu/menu.yaml +++ b/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 @@ -1033,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 diff --git a/persistence/sql/troubleshooting.md b/persistence/sql/troubleshooting.md index 53026803c1f..b62b683ba77 100644 --- a/persistence/sql/troubleshooting.md +++ b/persistence/sql/troubleshooting.md @@ -9,19 +9,4 @@ related: ## 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. \ No newline at end of file +include: sql-client4 \ No newline at end of file diff --git a/transports/upgrades/sqlserver-client4breakingchange.include.md b/persistence/upgrades/sql-client4.include.md similarity index 95% rename from transports/upgrades/sqlserver-client4breakingchange.include.md rename to persistence/upgrades/sql-client4.include.md index 182f2c6145c..e868efc1009 100644 --- a/transports/upgrades/sqlserver-client4breakingchange.include.md +++ b/persistence/upgrades/sql-client4.include.md @@ -1,5 +1,3 @@ -### `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: ``` diff --git a/persistence/upgrades/sql-client4.md b/persistence/upgrades/sql-client4.md new file mode 100644 index 00000000000..aaadd23d325 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/transports/sql/troubleshooting.md b/transports/sql/troubleshooting.md index ce8f2de009a..9d298b54714 100644 --- a/transports/sql/troubleshooting.md +++ b/transports/sql/troubleshooting.md @@ -9,19 +9,4 @@ related: ## 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. \ No newline at end of file +include: sql-client4 \ No newline at end of file diff --git a/transports/upgrades/sqlserver-5to6.md b/transports/upgrades/sqlserver-5to6.md index c575d23af5c..f480240429f 100644 --- a/transports/upgrades/sqlserver-5to6.md +++ b/transports/upgrades/sqlserver-5to6.md @@ -26,8 +26,6 @@ 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 diff --git a/transports/upgrades/sqlserver-6to7.md b/transports/upgrades/sqlserver-6to7.md index ddd1520e30e..148fc1a69a8 100644 --- a/transports/upgrades/sqlserver-6to7.md +++ b/transports/upgrades/sqlserver-6to7.md @@ -32,8 +32,6 @@ 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: diff --git a/transports/upgrades/sqlserver-client4.md b/transports/upgrades/sqlserver-client4.md new file mode 100644 index 00000000000..9e40f0644b2 --- /dev/null +++ b/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 \ No newline at end of file From 3ff8c6991e048c6e71af08f0859f31c6672093c9 Mon Sep 17 00:00:00 2001 From: Mike Minutillo Date: Mon, 28 Mar 2022 17:40:59 +0800 Subject: [PATCH 7/7] Apply suggestions from code review --- servicecontrol/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/servicecontrol/troubleshooting.md b/servicecontrol/troubleshooting.md index 6fd42b687fc..d628e8b13e2 100644 --- a/servicecontrol/troubleshooting.md +++ b/servicecontrol/troubleshooting.md @@ -76,7 +76,7 @@ System.Data.SqlClient.SqlException 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. +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).