Merge pull request #18002 from dotnet/publish-23474

BillWagner · web-flow · commit 348bb052d5ce · 2020-04-22T06:52:19.000-04:00
Merge master into live
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -121,9 +121,9 @@
 
 ################## .NET STANDARD ##################
 # Analyzers
-/docs/standard/analyzers/ @gewarren
+/docs/standard/analyzers/ @IEvangelist
 # Assembly
-/docs/standard/assembly/ @gewarren
+/docs/standard/assembly/ @IEvangelist
 # Asynchronous Programming Patterns
 /docs/standard/asynchronous-programming-patterns/ @BillWagner
 # Attributes
@@ -141,7 +141,7 @@
 # Design guidelines
 /docs/standard/design-guidelines/ @BillWagner
 # Events
-/docs/standard/events/ @gewarren
+/docs/standard/events/ @IEvangelist
 # Exceptions
 /docs/standard/exceptions/ @tdykstra
 # GC
@@ -163,7 +163,7 @@
 # Parallel programming
 /docs/standard/parallel-programming/ @BillWagner
 # Security
-/docs/standard/security/ @gewarren
+/docs/standard/security/ @IEvangelist
 # Serialization
 /docs/standard/serialization/ @tdykstra
 # Threading
diff --git a/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md b/.github/ISSUE_TEMPLATE/dotnet-breaking-change.md
@@ -43,7 +43,7 @@ Also, remove this comment before submitting the issue.
 - ASP.NET Core
 - C#
 - Core
-- CoreFx
+- Core .NET libraries
 - Data
 - Debugger
 - Deployment for .NET Core
diff --git a/docfx.json b/docfx.json
@@ -258,8 +258,8 @@
         "docs/machine-learning/**/**.md": "natke",
         "docs/spark/**/**.md": "mamccrea",
         "docs/standard/**/**.md": "gewarren",
-        "docs/standard/analyzers/**/**.md": "gewarren",
-        "docs/standard/assembly/**/**.md": "gewarren",
+        "docs/standard/analyzers/**/**.md": "IEvangelist",
+        "docs/standard/assembly/**/**.md": "IEvangelist",
         "docs/standard/asynchronous-programming-patterns/**/**.md": "billwagner",
         "docs/standard/attributes/**/**.md": "tdykstra",
         "docs/standard/base-types/**/**.md": "Thraka",
@@ -268,7 +268,7 @@
         "docs/standard/data/sqlite/**/**.md": "bricelam",
         "docs/standard/datetime/**/**.md": "Thraka",
         "docs/standard/design-guidelines/**/**.md": "KrzysztofCwalina",
-        "docs/standard/events/**/**.md": "gewarren",
+        "docs/standard/events/**/**.md": "IEvangelist",
         "docs/standard/exceptions/**/**.md": "tdykstra",
         "docs/standard/garbage-collection/**/**.md": "gewarren",
         "docs/standard/generics/**/**.md": "Thraka",
@@ -279,7 +279,7 @@
         "docs/standard/memory-and-spans/**/**.md": "tdykstra",
         "docs/standard/native-interop/**/**.md": "jkoritzinsky",
         "docs/standard/parallel-programming/**/**.md": "billwagner",
-        "docs/standard/security/**/**.md": "gewarren",
+        "docs/standard/security/**/**.md": "IEvangelist",
         "docs/standard/serialization/**/**.md": "tdykstra",
         "docs/standard/threading/**/**.md": "billwagner",
         "docs/standard/whats-new/**/**.md": "gewarren",
@@ -345,8 +345,8 @@
         "docs/machine-learning/**/**.md": "nakersha",
         "docs/spark/**/**.md": "mamccrea",
         "docs/standard/**/**.md": "gewarren",
-        "docs/standard/analyzers/**/**.md": "gewarren",
-        "docs/standard/assembly/**/**.md": "gewarren",
+        "docs/standard/analyzers/**/**.md": "dapine",
+        "docs/standard/assembly/**/**.md": "dapine",
         "docs/standard/asynchronous-programming-patterns/**/**.md": "wiwagn",
         "docs/standard/attributes/**/**.md": "tdykstra",
         "docs/standard/base-types/**/**.md": "adegeo",
@@ -355,7 +355,7 @@
         "docs/standard/data/sqlite/**/**.md": "bricelam",
         "docs/standard/datetime/**/**.md": "adegeo",
         "docs/standard/design-guidelines/**/**.md": "kcwalina",
-        "docs/standard/events/**/**.md": "gewarren",
+        "docs/standard/events/**/**.md": "dapine",
         "docs/standard/exceptions/**/**.md": "tdykstra",
         "docs/standard/garbage-collection/**/**.md": "gewarren",
         "docs/standard/generics/**/**.md": "adegeo",
@@ -366,7 +366,7 @@
         "docs/standard/memory-and-spans/**/**.md": "tdykstra",
         "docs/standard/native-interop/**/**.md": "jekoritz",
         "docs/standard/parallel-programming/**/**.md": "wiwagn",
-        "docs/standard/security/**/**.md": "gewarren",
+        "docs/standard/security/**/**.md": "dapine",
         "docs/standard/serialization/**/**.md": "tdykstra",
         "docs/standard/threading/**/**.md": "wiwagn",
         "docs/standard/whats-new/**/**.md": "dotnetcontent",
diff --git a/docs/core/compatibility/2.0-2.1.md b/docs/core/compatibility/2.0-2.1.md
@@ -7,7 +7,7 @@ ms.date: 12/17/2019
 
 If you're migrating from version 2.0 to version 2.1 of .NET Core, the breaking changes listed in this article may affect your app.
 
-## CoreFx
+## Core .NET libraries
 
 - [Private fields added to built-in struct types](#private-fields-added-to-built-in-struct-types)
 - [OpenSSL versions on macOS](#openssl-versions-on-macos)
diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md
@@ -260,7 +260,7 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core,
 
 ***
 
-## CoreFx
+## Core .NET libraries
 
 - [APIs that report version now report product and not file version](#apis-that-report-version-now-report-product-and-not-file-version)
 - [Custom EncoderFallbackBuffer instances cannot fall back recursively](#custom-encoderfallbackbuffer-instances-cannot-fall-back-recursively)
diff --git a/docs/core/compatibility/2.2-3.1.md b/docs/core/compatibility/2.2-3.1.md
@@ -263,7 +263,7 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core,
 
 [!INCLUDE[Target framework: .NET Framework not supported](~/includes/core-changes/aspnetcore/3.0/targetfx-netfx-tfm-support.md)]
 
-## CoreFx
+## Core .NET libraries
 
 - [APIs that report version now report product and not file version](#apis-that-report-version-now-report-product-and-not-file-version)
 - [Custom EncoderFallbackBuffer instances cannot fall back recursively](#custom-encoderfallbackbuffer-instances-cannot-fall-back-recursively)
diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md
@@ -1,11 +1,11 @@
 ---
 title: Base class library breaking changes
-description: Lists the breaking changes in .NET CoreFx, the base class library.
-ms.date: "09/20/2019"
+description: Lists the breaking changes in core .NET libraries.
+ms.date: 09/20/2019
 ---
-# CoreFx breaking changes
+# Core .NET libraries breaking changes
 
-CoreFx provides the primitives and other general types used by .NET Core.
+The core .NET libraries provide the primitives and other general types used by .NET Core.
 
 The following breaking changes are documented on this page:
 
diff --git a/docs/core/compatibility/fx-core.md b/docs/core/compatibility/fx-core.md
@@ -11,7 +11,7 @@ If you're migrating an app from .NET Framework to .NET Core, the breaking change
 > [!NOTE]
 > This article is not a complete list of breaking changes between .NET Framework and .NET Core. The most important breaking changes are added here as we become aware of them.
 
-## CoreFx
+## Core .NET libraries
 
 - [Change in default value of UseShellExecute](#change-in-default-value-of-useshellexecute)
 - [UnauthorizedAccessException thrown by FileSystemInfo.Attributes](#unauthorizedaccessexception-thrown-by-filesysteminfoattributes)
diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml
@@ -30,7 +30,7 @@
   items:
   - name: ASP.NET Core
     href: aspnetcore.md
-  - name: CoreFx
+  - name: Core .NET libraries
     href: corefx.md
   - name: Cryptography
     href: cryptography.md
diff --git a/docs/core/diagnostics/debug-memory-leak.md b/docs/core/diagnostics/debug-memory-leak.md
@@ -2,7 +2,7 @@
 title: Debug a memory leak tutorial
 description: Learn how to debug a memory leak in .NET Core.
 ms.topic: tutorial
-ms.date: 12/17/2019
+ms.date: 04/20/2020
 ---
 # Tutorial: Debug a memory leak in .NET Core
 
@@ -131,7 +131,7 @@ In this tutorial, you're now done with the [Sample debug target](https://docs.mi
 
 ### Analyze the core dump
 
-Now that you have a core dump generated, use the [dotnet-dump)](dotnet-dump.md) tool to analyze the dump:
+Now that you have a core dump generated, use the [dotnet-dump](dotnet-dump.md) tool to analyze the dump:
 
 ```dotnetcli
 dotnet-dump analyze core_20190430_185145
diff --git a/docs/core/tools/dotnet-restore.md b/docs/core/tools/dotnet-restore.md
@@ -114,7 +114,7 @@ Sometimes, it might be inconvenient to run `dotnet restore` implicitly. For exam
 
 - **`--no-cache`**
 
-  Specifies to not cache packages and HTTP requests.
+  Specifies to not cache HTTP requests.
 
 - **`--no-dependencies`**
 
diff --git a/docs/core/tools/global-json.md b/docs/core/tools/global-json.md
@@ -1,7 +1,7 @@
 ---
 title: global.json overview
 description: Learn how to use the global.json file to set the .NET Core SDK version when running .NET Core CLI commands.
-ms.date: 01/14/2020
+ms.date: 04/21/2020
 ms.custom: "updateeachrelease"
 ---
 # global.json overview
@@ -113,6 +113,17 @@ The following example shows how to use the exact specified version:
 }
 ```
 
+The following example shows how to use the latest feature band and patch version installed of a specific major and minor version:
+
+```json
+{
+  "sdk": {
+    "version": "3.1.000",
+    "rollForward": "latestFeature"
+  }
+}
+```
+
 The following example shows how to use the highest patch version installed of a specific version (in the form, 3.1.1xx):
 
 ```json
diff --git a/docs/csharp/language-reference/attributes/general.md b/docs/csharp/language-reference/attributes/general.md
@@ -13,33 +13,33 @@ The `Conditional` attribute makes the execution of a method dependent on a prepr
 
 In the following example, `Conditional` is applied to a method to enable or disable the display of program-specific diagnostic information:
 
-::::::code language="csharp" source="snippets/trace.cs" interactive="try-dotnet" :::
+:::code language="csharp" source="snippets/trace.cs" interactive="try-dotnet" :::
 
 If the `TRACE_ON` identifier isn't defined, the trace output isn't displayed. Explore for yourself in the interactive window.
 
 The `Conditional` attribute is often used with the `DEBUG` identifier to enable trace and logging features for debug builds but not in release builds, as shown in the following example:
 
-::::::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetConditional" :::
+:::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetConditional" :::
 
 When a method marked conditional is called, the presence or absence of the specified preprocessing symbol determines whether the call is included or omitted. If the symbol is defined, the call is included; otherwise, the call is omitted. A conditional method must be a method in a class or struct declaration and must have a `void` return type. Using `Conditional` is cleaner, more elegant, and less error-prone than enclosing methods inside `#if…#endif` blocks.
 
 If a method has multiple `Conditional` attributes, a call to the method is included if at one or more conditional symbols is defined (the symbols are logically linked together by using the OR operator). In the following example, the presence of either `A` or `B` results in a method call:
 
-::::::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetMultipleConditions" :::
+:::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetMultipleConditions" :::
 
 ### Using `Conditional` with attribute classes
 
 The `Conditional` attribute can also be applied to an attribute class definition. In the following example, the custom attribute `Documentation` will only add information to the metadata if `DEBUG` is defined.
 
-::::::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetConditionalConditionalAttribute" :::
+:::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetConditionalConditionalAttribute" :::
 
 ## `Obsolete` attribute
 
 The `Obsolete` attribute marks a code element as no longer recommended for use. Use of an entity marked obsolete generates a warning or an error. The `Obsolete` attribute is a single-use attribute and can be applied to any entity that allows attributes. `Obsolete` is an alias for <xref:System.ObsoleteAttribute>.
 
 In the following example the `Obsolete` attribute is applied to class `A` and to method `B.OldMethod`. Because the second argument of the attribute constructor applied to `B.OldMethod` is set to `true`, this method will cause a compiler error, whereas using class `A` will just produce a warning. Calling `B.NewMethod`, however, produces no warning or error. For example, when you use it with the previous definitions, the following code generates two warnings and one error:
 
-::::::code language="csharp" source="snippets/ObsoleteExample.cs" interactive="try-dotnet" :::
+:::code language="csharp" source="snippets/ObsoleteExample.cs" interactive="try-dotnet" :::
 
 The string provided as the first argument to the attribute constructor will be displayed as part of the warning or error. Two warnings for class `A` are generated: one for the declaration of the class reference, and one for the class constructor. The `Obsolete` attribute can be used without arguments, but including an explanation what to use instead is recommended.
 
diff --git a/docs/desktop-wpf/migration/differences-from-net-framework.md b/docs/desktop-wpf/migration/differences-from-net-framework.md
@@ -35,7 +35,7 @@ When your project uses `<PackageReference>`, packages aren't stored locally in a
 
 Code Access Security (CAS) is not supported by .NET Core or WPF for .NET Core. All CAS-related functionality is treated under the assumption of full-trust. WPF for .NET Core removes CAS-related code. The public API surface of these types still exists to ensure that calls into these types succeed.
 
-Publicly defined CAS-related types were moved out of the WPF assemblies and into the CoreFX assemblies. The WPF assemblies have type-forwarding set to the new location of the moved types.
+Publicly defined CAS-related types were moved out of the WPF assemblies and into the Core .NET library assemblies. The WPF assemblies have type-forwarding set to the new location of the moved types.
 
 | Source assembly | Target assembly | Type                |
 | --------------- | --------------- | ------------------- |
diff --git a/docs/fsharp/language-reference/import-declarations-the-open-keyword.md b/docs/fsharp/language-reference/import-declarations-the-open-keyword.md
@@ -20,7 +20,7 @@ open module-or-namespace-name
 
 Referencing code by using the fully qualified namespace or module path every time can create code that is hard to write, read, and maintain. Instead, you can use the `open` keyword for frequently used modules and namespaces so that when you reference a member of that module or namespace, you can use the short form of the name instead of the fully qualified name. This keyword is similar to the `using` keyword in C#, `using namespace` in Visual C++, and `Imports` in Visual Basic.
 
-The module or namespace provided must be in the same project or in a referenced project or assembly. If it is not, you can add a reference to the project, or use the `-reference` command`-`line option (or its abbreviation, `-r`). For more information, see [Compiler Options](compiler-options.md).
+The module or namespace provided must be in the same project or in a referenced project or assembly. If it is not, you can add a reference to the project, or use the `-reference` command-line option (or its abbreviation, `-r`). For more information, see [Compiler Options](compiler-options.md).
 
 The import declaration makes the names available in the code that follows the declaration, up to the end of the enclosing namespace, module, or file.
 
diff --git a/docs/machine-learning/how-to-guides/install-extra-dependencies.md b/docs/machine-learning/how-to-guides/install-extra-dependencies.md
@@ -82,7 +82,7 @@ No extra installation steps required. The library is installed when the NuGet pa
 5. Add this location to the load library path:
 
     ```bash
-    sudo ldconfig /opt/intel/compilers_and_libraries_2020.0.166/linux/compiler/lib/intel64_li
+    sudo ldconfig /opt/intel/compilers_and_libraries_2020.0.166/linux/compiler/lib/intel64_lin
     ```
 
 ### Mac
diff --git a/docs/standard/parallel-programming/exception-handling-task-parallel-library.md b/docs/standard/parallel-programming/exception-handling-task-parallel-library.md
@@ -1,6 +1,6 @@
 ---
 title: "Exception handling (Task Parallel Library)"
-ms.date: "03/30/2017"
+ms.date: 04/20/2020
 ms.technology: dotnet-standard
 dev_langs: 
   - "csharp"
@@ -83,7 +83,14 @@ If a task completes in the <xref:System.Threading.Tasks.TaskStatus.Faulted?displ
 [!code-csharp[TPL_Exceptions#27](../../../samples/snippets/csharp/VS_Snippets_Misc/tpl_exceptions/cs/exceptionprop21.cs#27)]
 [!code-vb[TPL_Exceptions#27](../../../samples/snippets/visualbasic/VS_Snippets_Misc/tpl_exceptions/vb/exceptionprop21.vb#27)]
 
-In a real application, the continuation delegate could log detailed information about the exception and possibly spawn new tasks to recover from the exception.
+In a meaningful application, the continuation delegate could log detailed information about the exception and possibly spawn new tasks to recover from the exception. If a task faults, the following expressions throw the exception:
+
+- `await task`
+- `task.Wait()`
+- `task.Result`
+- `task.GetAwaiter().GetResult()`
+
+Use a [`try-catch`](../../csharp/language-reference/keywords/try-catch.md) statement to handle and observe thrown exceptions. Alternatively, observe the exception by accessing the <xref:System.Threading.Tasks.Task.Exception%2A?displayProperty=nameWithType> property.
 
 ## UnobservedTaskException event
 
diff --git a/includes/core-changes/categoryselector.md b/includes/core-changes/categoryselector.md
@@ -1,7 +1,7 @@
 > [!div class="op_single_selector"]
 >
 > - [ASP.NET Core](~/docs/core/compatibility/aspnetcore.md)
-> - [CoreFx](~/docs/core/compatibility/corefx.md)
+> - [Core .NET libraries](~/docs/core/compatibility/corefx.md)
 > - [Cryptography](~/docs/core/compatibility/cryptography.md)
 > - [EF Core](/ef/core/what-is-new/ef-core-3.0/breaking-changes)
 > - [Globalization](~/docs/core/compatibility/globalization.md)
diff --git a/includes/core-changes/corefx/1.0/filesysteminfo-attributes-exceptions.md b/includes/core-changes/corefx/1.0/filesysteminfo-attributes-exceptions.md
@@ -16,7 +16,7 @@ Modify any `catch` statements to catch an <xref:System.UnauthorizedAccessExcepti
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/2.1/instantiate-struct.md b/includes/core-changes/corefx/2.1/instantiate-struct.md
@@ -45,7 +45,7 @@ if (key.ToString() == "y")
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/2.1/process-start-changes.md b/includes/core-changes/corefx/2.1/process-start-changes.md
@@ -21,7 +21,7 @@ If your app relies on the old behavior, call <xref:System.Diagnostics.Process.St
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/change-in-null-in-utf8jsonwriter.md b/includes/core-changes/corefx/3.0/change-in-null-in-utf8jsonwriter.md
@@ -62,7 +62,7 @@ When writing property names and values with the <xref:System.Text.Json.Utf8JsonW
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/custom-encoderfallbackbuffer-cannot-be-recursive.md b/includes/core-changes/corefx/3.0/custom-encoderfallbackbuffer-cannot-be-recursive.md
@@ -30,7 +30,7 @@ If an application uses a custom <xref:System.Text.EncoderFallback> and <xref:Sys
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/fieldinfo-setvalue-exception.md b/includes/core-changes/corefx/3.0/fieldinfo-setvalue-exception.md
@@ -23,7 +23,7 @@ Alternatively, you can remove the <xref:System.Reflection.FieldAttributes.InitOn
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/floating-point-changes.md b/includes/core-changes/corefx/3.0/floating-point-changes.md
@@ -18,7 +18,7 @@ The "Potential impact to existing code" section of the [Floating-point parsing a
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/floating-point-parsing-does-not-overflow.md b/includes/core-changes/corefx/3.0/floating-point-parsing-does-not-overflow.md
@@ -24,7 +24,7 @@ This change can affect your code in either of two ways:
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/jsonencodedtext-encode-has-additional-argument.md b/includes/core-changes/corefx/3.0/jsonencodedtext-encode-has-additional-argument.md
@@ -44,7 +44,7 @@ This is a binary breaking change only; a recompile against .NET Core 3.0 Preview
 
 #### Category
 
-CoreFx
+Core .NET libraries
 
 #### Affected APIs
 
diff --git a/includes/core-changes/corefx/3.0/move-invalidasynchronousstateexception.md b/includes/core-changes/corefx/3.0/move-invalidasynchronousstateexception.md
diff --git a/includes/core-changes/corefx/3.0/net-core-3-0-follows-unicode-utf8-best-practices.md b/includes/core-changes/corefx/3.0/net-core-3-0-follows-unicode-utf8-best-practices.md
diff --git a/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md b/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md
diff --git a/includes/core-changes/corefx/3.0/version-information-changes.md b/includes/core-changes/corefx/3.0/version-information-changes.md
diff --git a/includes/core-changes/corefx/openssl-dependencies-macos.md b/includes/core-changes/corefx/openssl-dependencies-macos.md
