Document Exception Handler Middleware breaking change (#20542)

* Document Exception Handler Middleware breaking change

* Add link to discussion issue

* Update includes/core-changes/aspnetcore/5.0/middleware-exception-handler-throws-original-exception.md

Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com>

Co-authored-by: Youssef Victor <31348972+Youssef1313@users.noreply.github.com>

Author: scottaddie

docs/core/compatibility/3.1-5.0.md

@@ -1,7 +1,7 @@
 ---
 title: Breaking changes, version 3.1 to 5.0
 description: Lists the breaking changes from version 3.1 to version 5.0 of .NET, ASP.NET Core, and EF Core.
-ms.date: 09/02/2020
+ms.date: 09/09/2020
 ---
 # Breaking changes for migration from version 3.1 to 5.0
 
@@ -26,6 +26,7 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 - [Localization: Obsolete constructor removed in request localization middleware](#localization-obsolete-constructor-removed-in-request-localization-middleware)
 - [Localization: ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed](#localization-resourcemanagerwithculturestringlocalizer-class-and-withculture-interface-member-removed)
 - [Middleware: Database error page marked as obsolete](#middleware-database-error-page-marked-as-obsolete)
+- [Middleware: Exception Handler Middleware throws original exception if handler not found](#middleware-exception-handler-middleware-throws-original-exception-if-handler-not-found)
 - [Security: Cookie name encoding removed](#security-cookie-name-encoding-removed)
 - [Security: IdentityModel NuGet package versions updated](#security-identitymodel-nuget-package-versions-updated)
 - [SignalR: MessagePack Hub Protocol moved to MessagePack 2.x package](#signalr-messagepack-hub-protocol-moved-to-messagepack-2x-package)
@@ -101,6 +102,10 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v
 
 ***
 
+[!INCLUDE[Middleware: Exception Handler Middleware throws original exception if handler not found](~/includes/core-changes/aspnetcore/5.0/middleware-exception-handler-throws-original-exception.md)]
+
+***
+
 [!INCLUDE[Security: Cookie name encoding removed](~/includes/core-changes/aspnetcore/5.0/security-cookie-name-encoding-removed.md)]
 
 ***

docs/core/compatibility/aspnetcore.md

@@ -2,7 +2,7 @@
 title: ASP.NET Core breaking changes
 titleSuffix: ""
 description: Lists the breaking changes in ASP.NET Core.
-ms.date: 08/25/2020
+ms.date: 09/09/2020
 author: scottaddie
 ms.author: scaddie
 ---
@@ -70,6 +70,7 @@ The following breaking changes in ASP.NET Core 3.0, 3.1, and 5.0 are documented
 - [Localization: ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed](#localization-resourcemanagerwithculturestringlocalizer-class-and-withculture-interface-member-removed)
 - [Logging: DebugLogger class made internal](#logging-debuglogger-class-made-internal)
 - [Middleware: Database error page marked as obsolete](#middleware-database-error-page-marked-as-obsolete)
+- [Middleware: Exception Handler Middleware throws original exception if handler not found](#middleware-exception-handler-middleware-throws-original-exception-if-handler-not-found)
 - [MVC: Controller action Async suffix removed](#mvc-async-suffix-trimmed-from-controller-action-names)
 - [MVC: JsonResult moved to Microsoft.AspNetCore.Mvc.Core](#mvc-jsonresult-moved-to-microsoftaspnetcoremvccore)
 - [MVC: Precompilation tool deprecated](#mvc-precompilation-tool-deprecated)
@@ -168,6 +169,10 @@ The following breaking changes in ASP.NET Core 3.0, 3.1, and 5.0 are documented
 
 ***
 
+[!INCLUDE[Middleware: Exception Handler Middleware throws original exception if handler not found](~/includes/core-changes/aspnetcore/5.0/middleware-exception-handler-throws-original-exception.md)]
+
+***
+
 [!INCLUDE[Security: Cookie name encoding removed](~/includes/core-changes/aspnetcore/5.0/security-cookie-name-encoding-removed.md)]
 
 ***

includes/core-changes/aspnetcore/5.0/middleware-exception-handler-throws-original-exception.md

@@ -0,0 +1,49 @@
+### Middleware: Exception Handler Middleware throws original exception if handler not found
+
+Before ASP.NET Core 5.0, the [Exception Handler Middleware](xref:Microsoft.AspNetCore.Builder.ExceptionHandlerExtensions.UseExceptionHandler%2A) executes the configured exception handler when an exception has occurred. If the exception handler, configured via <xref:Microsoft.AspNetCore.Builder.ExceptionHandlerOptions.ExceptionHandlingPath>, can't be found, an HTTP 404 response is produced. The response is misleading in that it:
+
+* Seems to be a user error.
+* Obscures the fact that an exception occurred on the server.
+
+To address the misleading error in ASP.NET Core 5.0, the `ExceptionHandlerMiddleware` throws the original exception if the exception handler can't be found. As a result, an HTTP 500 response is produced by the server. The response will be easier to examine in the server logs when debugging the error that occurred.
+
+For discussion, see GitHub issue [dotnet/aspnetcore#25288](https://github.com/dotnet/aspnetcore/issues/25288).
+
+#### Version introduced
+
+5.0 RC 1
+
+#### Old behavior
+
+The Exception Handler Middleware produces an HTTP 404 response if the configured exception handler can't be found.
+
+#### New behavior
+
+The Exception Handler Middleware throws the original exception if the configured exception handler can't be found.
+
+#### Reason for change
+
+The HTTP 404 error doesn't make it obvious that an exception occurred on the server. This change produces an HTTP 500 error to make it obvious that:
+
+* The problem isn't caused by a user error.
+* An exception was encountered on the server.
+
+#### Recommended action
+
+There are no API changes. All existing apps will continue to compile and run. The exception thrown is handled by the server. For example, the exception is converted to an HTTP 500 error response by [Kestrel](/aspnet/core/fundamentals/servers/kestrel) or [HTTP.sys](/aspnet/core/fundamentals/servers/httpsys).
+
+#### Category
+
+ASP.NET Core
+
+#### Affected APIs
+
+None
+
+<!--
+
+#### Affected APIs
+
+Not detectable via API analysis
+
+-->