Merge pull request #17678 from dotnet/master

scottaddie · web-flow · commit ed12f77a576d · 2020-04-08T15:53:58.000-05:00
Update live with master
diff --git a/aspnetcore/blazor/call-dotnet-from-javascript.md b/aspnetcore/blazor/call-dotnet-from-javascript.md
@@ -5,7 +5,7 @@ description: Learn how to invoke .NET methods from JavaScript functions in Blazo
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 03/24/2020
+ms.date: 04/07/2020
 no-loc: [Blazor, SignalR]
 uid: blazor/call-dotnet-from-javascript
 ---
@@ -352,6 +352,18 @@ window.updateMessageCallerJS = (dotnetHelper) => {
 
 [!INCLUDE[Share interop code in a class library](~/includes/blazor-share-interop-code.md)]
 
+## Avoid circular object references
+
+Objects that contain circular references can't be serialized on the client for either:
+
+* .NET method calls.
+* JavaScript method calls from C# when the return type has circular references.
+
+For more information, see the following issues:
+
+* [Circular references are not supported, take two (dotnet/aspnetcore #20525)](https://github.com/dotnet/aspnetcore/issues/20525)
+* [Proposal: Add mechanism to handle circular references when serializing (dotnet/runtime #30820)](https://github.com/dotnet/runtime/issues/30820)
+
 ## Additional resources
 
 * <xref:blazor/call-javascript-from-dotnet>
diff --git a/aspnetcore/blazor/call-javascript-from-dotnet.md b/aspnetcore/blazor/call-javascript-from-dotnet.md
@@ -5,7 +5,7 @@ description: Learn how to invoke JavaScript functions from .NET methods in Blazo
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 02/19/2020
+ms.date: 04/07/2020
 no-loc: [Blazor, SignalR]
 uid: blazor/call-javascript-from-dotnet
 ---
@@ -454,6 +454,18 @@ For more information on resource exhaustion, see <xref:security/blazor/server>.
 
 [!INCLUDE[Share interop code in a class library](~/includes/blazor-share-interop-code.md)]
 
+## Avoid circular object references
+
+Objects that contain circular references can't be serialized on the client for either:
+
+* .NET method calls.
+* JavaScript method calls from C# when the return type has circular references.
+
+For more information, see the following issues:
+
+* [Circular references are not supported, take two (dotnet/aspnetcore #20525)](https://github.com/dotnet/aspnetcore/issues/20525)
+* [Proposal: Add mechanism to handle circular references when serializing (dotnet/runtime #30820)](https://github.com/dotnet/runtime/issues/30820)
+
 ## Additional resources
 
 * <xref:blazor/call-dotnet-from-javascript>
diff --git a/aspnetcore/blazor/globalization-localization.md b/aspnetcore/blazor/globalization-localization.md
@@ -5,7 +5,7 @@ description: Learn how to make Razor components accessible to users in multiple
 monikerRange: '>= aspnetcore-3.1'
 ms.author: riande
 ms.custom: mvc
-ms.date: 04/02/2020
+ms.date: 04/07/2020
 no-loc: [Blazor, SignalR]
 uid: blazor/globalization-localization
 ---
@@ -154,7 +154,7 @@ The following component shows an example of how to perform the initial redirecti
     private void OnSelected(ChangeEventArgs e)
     {
         var culture = (string)e.Value;
-        var uri = new Uri(NavigationManager.Uri())
+        var uri = new Uri(NavigationManager.Uri)
             .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
         var query = $"?culture={Uri.EscapeDataString(culture)}&" +
             $"redirectUri={Uri.EscapeDataString(uri)}";
diff --git a/aspnetcore/fundamentals/servers/kestrel.md b/aspnetcore/fundamentals/servers/kestrel.md
@@ -339,14 +339,14 @@ webBuilder.ConfigureKestrel(serverOptions =>
 
 The default value is 96 KB (98,304).
 
-### Synchronous IO
+### Synchronous I/O
 
-<xref:Microsoft.AspNetCore.Server.Kestrel.Core.KestrelServerOptions.AllowSynchronousIO> controls whether synchronous IO is allowed for the request and response. The default value is `false`.
+<xref:Microsoft.AspNetCore.Server.Kestrel.Core.KestrelServerOptions.AllowSynchronousIO> controls whether synchronous I/O is allowed for the request and response. The default value is `false`.
 
 > [!WARNING]
-> A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous IO.
+> A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous I/O.
 
-The following example enables synchronous IO:
+The following example enables synchronous I/O:
 
 [!code-csharp[](kestrel/samples/3.x/KestrelSample/Program.cs?name=snippet_SyncIO)]
 
@@ -1320,14 +1320,14 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
 
 The default value is 96 KB (98,304).
 
-### Synchronous IO
+### Synchronous I/O
 
-<xref:Microsoft.AspNetCore.Server.Kestrel.Core.KestrelServerOptions.AllowSynchronousIO> controls whether synchronous IO is allowed for the request and response. The  default value is `true`.
+<xref:Microsoft.AspNetCore.Server.Kestrel.Core.KestrelServerOptions.AllowSynchronousIO> controls whether synchronous I/O is allowed for the request and response. The  default value is `true`.
 
 > [!WARNING]
-> A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous IO.
+> A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous I/O.
 
-The following example enables synchronous IO:
+The following example enables synchronous I/O:
 
 [!code-csharp[](kestrel/samples/2.x/KestrelSample/Program.cs?name=snippet_SyncIO)]
 
@@ -2177,14 +2177,14 @@ public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
         });
 ```
 
-### Synchronous IO
+### Synchronous I/O
 
-<xref:Microsoft.AspNetCore.Server.Kestrel.Core.KestrelServerOptions.AllowSynchronousIO> controls whether synchronous IO is allowed for the request and response. The  default value is `true`.
+<xref:Microsoft.AspNetCore.Server.Kestrel.Core.KestrelServerOptions.AllowSynchronousIO> controls whether synchronous I/O is allowed for the request and response. The  default value is `true`.
 
 > [!WARNING]
-> A large number of blocking synchronous IO operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous IO.
+> A large number of blocking synchronous I/O operations can lead to thread pool starvation, which makes the app unresponsive. Only enable `AllowSynchronousIO` when using a library that doesn't support asynchronous I/O.
 
-The following example disables synchronous IO:
+The following example disables synchronous I/O:
 
 ```csharp
 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
diff --git a/aspnetcore/fundamentals/target-aspnetcore.md b/aspnetcore/fundamentals/target-aspnetcore.md
@@ -201,7 +201,7 @@ If you can't rewrite the library, take the following steps:
 * Add a `<FrameworkReference>` element for the shared framework.
 * Use the [#if preprocessor directive](/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-if) with the appropriate target framework symbol to conditionally compile code.
 
-For example, synchronous reads and writes on HTTP request and response streams are disabled by default as of ASP.NET Core 3.0. ASP.NET Core 2.2 supports the synchronous behavior by default. Consider a middleware library in which synchronous reads and writes should be enabled where IO is occurring. The library should enclose the code to enable synchronous features in the appropriate preprocessor directive. For example:
+For example, synchronous reads and writes on HTTP request and response streams are disabled by default as of ASP.NET Core 3.0. ASP.NET Core 2.2 supports the synchronous behavior by default. Consider a middleware library in which synchronous reads and writes should be enabled where I/O is occurring. The library should enclose the code to enable synchronous features in the appropriate preprocessor directive. For example:
 
 [!code-csharp[](target-aspnetcore/samples/middleware.cs?highlight=9-24)]
 
diff --git a/aspnetcore/grpc/browser.md b/aspnetcore/grpc/browser.md
@@ -43,6 +43,11 @@ Alternatively, configure all services to support gRPC-Web by adding `services.Ad
 
 [!code-csharp[](~/grpc/browser/sample/AllServicesSupportExample_Startup.cs?name=snippet_1&highlight=6,13)]
 
+> [!NOTE]
+> There is a known issue that causes gRPC-Web to fail when [hosted by Http.sys](xref:fundamentals/servers/httpsys) in .NET Core 3.x.
+>
+> A workaround to get gRPC-Web working on Http.sys is available [here](https://github.com/grpc/grpc-dotnet/issues/853#issuecomment-610078202).
+
 ### gRPC-Web and CORS
 
 Browser security prevents a web page from making requests to a different domain than the one that served the web page. This restriction applies to making gRPC-Web calls with browser apps. For example, a browser app served by `https://www.contoso.com` is blocked from calling gRPC-Web services hosted on `https://services.contoso.com`. Cross Origin Resource Sharing (CORS) can be used to relax this restriction.
diff --git a/aspnetcore/host-and-deploy/iis/index.md b/aspnetcore/host-and-deploy/iis/index.md
@@ -118,7 +118,7 @@ services.Configure<IISServerOptions>(options =>
 | ------------------------------ | :-----: | ------- |
 | `AutomaticAuthentication`      | `true`  | If `true`, IIS Server sets the `HttpContext.User` authenticated by [Windows Authentication](xref:security/authentication/windowsauth). If `false`, the server only provides an identity for `HttpContext.User` and responds to challenges when explicitly requested by the `AuthenticationScheme`. Windows Authentication must be enabled in IIS for `AutomaticAuthentication` to function. For more information, see [Windows Authentication](xref:security/authentication/windowsauth). |
 | `AuthenticationDisplayName`    | `null`  | Sets the display name shown to users on login pages. |
-| `AllowSynchronousIO`           | `false` | Whether synchronous IO is allowed for the `HttpContext.Request` and the `HttpContext.Response`. |
+| `AllowSynchronousIO`           | `false` | Whether synchronous I/O is allowed for the `HttpContext.Request` and the `HttpContext.Response`. |
 | `MaxRequestBodySize`           | `30000000`  | Gets or sets the max request body size for the `HttpRequest`. Note that IIS itself has the limit `maxAllowedContentLength` which will be processed before the `MaxRequestBodySize` set in the `IISServerOptions`. Changing the `MaxRequestBodySize` won't affect the `maxAllowedContentLength`. To increase `maxAllowedContentLength`, add an entry in the *web.config* to set `maxAllowedContentLength` to a higher value. For more details, see [Configuration](/iis/configuration/system.webServer/security/requestFiltering/requestLimits/#configuration). |
 
 **Out-of-process hosting model**
diff --git a/aspnetcore/includes/MTcomments.md b/aspnetcore/includes/MTcomments.md
@@ -1 +1 @@
-If you are reading this in a language other than English, let us know in this [GitHub discussion issue](https://github.com/aspnet/AspNetCore.Docs/issues/16455) if you’d like to see the code comments in your native language.
+If you are reading this in a language other than English, let us know in this [GitHub discussion issue](https://github.com/aspnet/AspNetCore.Docs/issues/16455) if you'd like to see the code comments in your native language.
diff --git a/aspnetcore/migration/22-to-30.md b/aspnetcore/migration/22-to-30.md
@@ -408,9 +408,9 @@ For more information, see [Put request trailers in a separate collection (dotnet
 
 ### AllowSynchronousIO disabled
 
-`AllowSynchronousIO` enables or disables synchronous IO APIs, such as `HttpRequest.Body.Read`, `HttpResponse.Body.Write`, and `Stream.Flush`. These APIs are a source of thread starvation leading to app crashes. In 3.0, `AllowSynchronousIO` is disabled by default. For more information, see [the Synchronous IO section in the Kestrel article](/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.0#synchronous-io).
+`AllowSynchronousIO` enables or disables synchronous I/O APIs, such as `HttpRequest.Body.Read`, `HttpResponse.Body.Write`, and `Stream.Flush`. These APIs are a source of thread starvation leading to app crashes. In 3.0, `AllowSynchronousIO` is disabled by default. For more information, see [the Synchronous I/O section in the Kestrel article](/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.0#synchronous-io).
 
-If synchronous IO is needed, it can be enabled by configuring the `AllowSynchronousIO` option on the server being used (when calling `ConfigureKestrel`, for example, if using Kestrel). Note that servers (Kestrel, HttpSys, TestServer, etc.) all have their own `AllowSynchronousIO` option that won't affect other servers. Synchronous IO can be enabled for all servers on a per-request basis using the `IHttpBodyControlFeature.AllowSynchronousIO` option:
+If synchronous I/O is needed, it can be enabled by configuring the `AllowSynchronousIO` option on the server being used (when calling `ConfigureKestrel`, for example, if using Kestrel). Note that servers (Kestrel, HttpSys, TestServer, etc.) all have their own `AllowSynchronousIO` option that won't affect other servers. Synchronous I/O can be enabled for all servers on a per-request basis using the `IHttpBodyControlFeature.AllowSynchronousIO` option:
 
 ```csharp
 var syncIOFeature = HttpContext.Features.Get<IHttpBodyControlFeature>();
diff --git a/aspnetcore/mvc/controllers/routing.md b/aspnetcore/mvc/controllers/routing.md
@@ -677,7 +677,7 @@ The following example uses attribute routing:
 
 The `Source` action in the preceding code generates `custom/url/to/destination`.
 
-<xref:Microsoft.AspNetCore.Routing.LinkGenerator> was added in ASP.NET Core 3.0 as an alternative to `IUrlHelper`. `LinkGenerator` offers similar but more flexible functionality. Each other the methods on `IUrlHelper` has a corresponding family of methods on `LinkGenerator` as well.
+<xref:Microsoft.AspNetCore.Routing.LinkGenerator> was added in ASP.NET Core 3.0 as an alternative to `IUrlHelper`. `LinkGenerator` offers similar but more flexible functionality. Each method on `IUrlHelper` has a corresponding family of methods on `LinkGenerator` as well.
 
 ### Generating URLs by action name
 
diff --git a/aspnetcore/mvc/controllers/testing/samples/3.x/TestingControllersSample/tests/global.json b/aspnetcore/mvc/controllers/testing/samples/3.x/TestingControllersSample/tests/global.json
@@ -1,5 +1,5 @@
 {
   "sdk": {
-    "version": 3.0.100"
+    "version": "3.0.100"
   }
-}
+}
diff --git a/aspnetcore/performance/performance-best-practices.md b/aspnetcore/performance/performance-best-practices.md
@@ -4,7 +4,7 @@ author: mjrousos
 description: Tips for increasing performance in ASP.NET Core apps and avoiding common performance problems.
 monikerRange: '>= aspnetcore-2.1'
 ms.author: riande
-ms.date: 12/05/2019
+ms.date: 04/06/2020
 no-loc: [SignalR]
 uid: performance/performance-best-practices
 ---
@@ -95,7 +95,7 @@ Recommendations:
 
 ## Keep common code paths fast
 
-You want all of your code to be fast, frequently called code paths are the most critical to optimize:
+You want all of your code to be fast. Frequently-called code paths are the most critical to optimize. These include:
 
 * Middleware components in the app's request processing pipeline, especially middleware run early in the pipeline. These components have a large impact on performance.
 * Code that's executed for every request or multiple times per request. For example, custom logging, authorization handlers, or initialization of transient services.
@@ -153,7 +153,7 @@ The following sections provide performance tips and known reliability problems a
 
 ## Avoid synchronous read or write on HttpRequest/HttpResponse body
 
-All IO in ASP.NET Core is asynchronous. Servers implement the `Stream` interface, which has both synchronous and asynchronous overloads. The asynchronous ones should be preferred to avoid blocking thread pool threads. Blocking threads can lead to thread pool starvation.
+All I/O in ASP.NET Core is asynchronous. Servers implement the `Stream` interface, which has both synchronous and asynchronous overloads. The asynchronous ones should be preferred to avoid blocking thread pool threads. Blocking threads can lead to thread pool starvation.
 
 **Do not do this:** The following example uses the <xref:System.IO.StreamReader.ReadToEnd*>. It blocks the current thread to wait for the result. This is an example of [sync over async](https://github.com/davidfowl/AspNetCoreDiagnosticScenarios/blob/master/AsyncGuidance.md#warning-sync-over-async
 ).
@@ -205,7 +205,7 @@ In .NET, every object allocation greater than 85 KB ends up in the large object
 
 This [blog post](https://adamsitnik.com/Array-Pool/#the-problem) describes the problem succinctly:
 
-> When a large object is allocated, it’s marked as Gen 2 object. Not Gen 0 as for small objects. The consequences are that if you run out of memory in LOH, GC cleans up the whole managed heap, not only LOH. So it cleans up Gen 0, Gen 1 and Gen 2 including LOH. This is called full garbage collection and is the most time-consuming garbage collection. For many applications, it can be acceptable. But definitely not for high-performance web servers, where few big memory buffers are needed to handle an average web request (read from a socket, decompress, decode JSON & more).
+> When a large object is allocated, it's marked as Gen 2 object. Not Gen 0 as for small objects. The consequences are that if you run out of memory in LOH, GC cleans up the whole managed heap, not only LOH. So it cleans up Gen 0, Gen 1 and Gen 2 including LOH. This is called full garbage collection and is the most time-consuming garbage collection. For many applications, it can be acceptable. But definitely not for high-performance web servers, where few big memory buffers are needed to handle an average web request (read from a socket, decompress, decode JSON & more).
 
 Naively storing a large request or response body into a single `byte[]` or `string`:
 
@@ -231,7 +231,7 @@ ASP.NET Core 3.0 uses <xref:System.Text.Json> by default for JSON serialization.
 
 The [IHttpContextAccessor.HttpContext](xref:Microsoft.AspNetCore.Http.IHttpContextAccessor.HttpContext) returns the `HttpContext` of the active request when accessed from the request thread. The `IHttpContextAccessor.HttpContext` should **not** be stored in a field or variable.
 
-**Do not do this:** The following example stores the `HttpContext` in a field, and then attempts to use it later.
+**Do not do this:** The following example stores the `HttpContext` in a field and then attempts to use it later.
 
 [!code-csharp[](performance-best-practices/samples/3.0/MyType.cs?name=snippet1)]
 
@@ -268,7 +268,7 @@ The preceding code frequently captures a null or incorrect `HttpContext` in the
 
 [!code-csharp[](performance-best-practices/samples/3.0/Controllers/AsyncBadVoidController.cs?name=snippet1)]
 
-**Do this:** The following example returns a `Task` to the framework so the HTTP request doesn't complete until the action completes.
+**Do this:** The following example returns a `Task` to the framework, so the HTTP request doesn't complete until the action completes.
 
 [!code-csharp[](performance-best-practices/samples/3.0/Controllers/AsyncSecondController.cs?name=snippet1)]
 
diff --git a/aspnetcore/release-notes/aspnetcore-2.2.md b/aspnetcore/release-notes/aspnetcore-2.2.md
@@ -100,7 +100,7 @@ ASP.NET Core web project templates were updated to [Bootstrap 4](https://getboot
 
 ## Validation performance
 
-MVC’s validation system is designed to be extensible and flexible, allowing you to determine on a per request basis which validators apply to a given model. This is great for authoring complex validation providers. However, in the most common case an application only uses the built-in validators and don’t require this extra flexibility. Built-in validators include DataAnnotations such as [Required] and [StringLength], and `IValidatableObject`.
+MVC's validation system is designed to be extensible and flexible, allowing you to determine on a per request basis which validators apply to a given model. This is great for authoring complex validation providers. However, in the most common case an application only uses the built-in validators and don't require this extra flexibility. Built-in validators include DataAnnotations such as [Required] and [StringLength], and `IValidatableObject`.
 
 In ASP.NET Core 2.2, MVC can short-circuit validation if it determines that a given model graph doesn't require validation. Skipping validation results in significant improvements when validating models that can't or don't have any validators. This includes objects such as collections of primitives (such as `byte[]`, `string[]`, `Dictionary<string, string>`), or complex object graphs without many validators.
 
diff --git a/aspnetcore/release-notes/aspnetcore-3.0.md b/aspnetcore/release-notes/aspnetcore-3.0.md
diff --git a/aspnetcore/security/data-protection/implementation/key-storage-format.md b/aspnetcore/security/data-protection/implementation/key-storage-format.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-If you are reading this in a language other than English, let us know in this [GitHub discussion issue](https://github.com/aspnet/AspNetCore.Docs/issues/16455) if you’d like to see the code comments in your native language.`
	`1`	`+If you are reading this in a language other than English, let us know in this [GitHub discussion issue](https://github.com/aspnet/AspNetCore.Docs/issues/16455) if you'd like to see the code comments in your native language.`