Merge pull request #36469 from dotnet/main

.openpublishing.redirection.fundamentals.json

@@ -4,6 +4,18 @@
             "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1071.md",
             "redirect_url": "/dotnet/fundamentals/code-analysis/quality-rules/index"
         },
+        {
+            "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1865.md",
+            "redirect_url": "/docs/fundamentals/code-analysis/quality-rules/ca1865-ca1867"
+        },
+        {
+            "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1866.md",
+            "redirect_url": "/docs/fundamentals/code-analysis/quality-rules/ca1865-ca1867"
+        },
+        {
+            "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/ca1867.md",
+            "redirect_url": "/docs/fundamentals/code-analysis/quality-rules/ca1865-ca1867"
+        },
         {
             "source_path_from_root": "/docs/fundamentals/code-analysis/quality-rules/singlefile-warnings.md",
             "redirect_url": "/dotnet/core/deploying/single-file/warnings/overview"

docs/core/compatibility/3.1.md

@@ -1,16 +1,14 @@
 ---
 title: Breaking changes in .NET Core 3.1
 description: Lists the breaking changes in version 3.1 of .NET Core and ASP.NET Core.
-ms.date: 06/22/2022
+ms.date: 07/28/2023
 ---
 # Breaking changes in .NET Core 3.1
 
 If you're migrating to version 3.1 of .NET Core or ASP.NET Core, the breaking changes listed in this article may affect your app.
 
 ## ASP.NET Core
 
-- [HTTP: Browser SameSite changes impact authentication](#http-browser-samesite-changes-impact-authentication)
-
 [!INCLUDE[HTTP: Browser SameSite changes impact authentication](~/includes/core-changes/aspnetcore/3.1/http-cookie-samesite-authn-impacts.md)]
 
 ***
@@ -21,16 +19,15 @@ If you're migrating to version 3.1 of .NET Core or ASP.NET Core, the breaking ch
 
 ## MSBuild
 
-- [Design-time builds only return top-level package references](#design-time-builds-only-return-top-level-package-references)
-
 [!INCLUDE [design-time-builds-return-top-level-package-refs](../../../includes/core-changes/msbuild/3.1/design-time-builds-return-top-level-package-refs.md)]
 
 ***
 
-## Windows Forms
+## SDK
 
-- [Removed controls](#removed-controls)
-- [CellFormatting event not raised if tooltip is shown](#cellformatting-event-not-raised-if-tooltip-is-shown)
+[Tool manifests in root folder](sdk/7.0/manifest-search.md)
+
+## Windows Forms
 
 [!INCLUDE[Removed controls](~/includes/core-changes/windowsforms/3.1/remove-controls-3.1.md)]
 

docs/core/compatibility/6.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 6
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 6.
-ms.date: 06/22/2022
+ms.date: 07/28/2023
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # Breaking changes in .NET 6
@@ -145,6 +145,7 @@ For information on other breaking changes for containers in .NET 6, see [.NET 6
 | [Publish ReadyToRun with --no-restore requires changes](sdk/6.0/publish-readytorun-requires-restore-change.md) | ✔️ | ❌ | 6.0.100 |
 | [runtimeconfig.dev.json file not generated](sdk/6.0/runtimeconfigdev-file.md) | ❌ | ✔️ | 6.0.100 |
 | [RuntimeIdentifier warning if self-contained is unspecified](sdk/6.0/runtimeidentifier-self-contained.md) | ✔️ | ❌ | RC 1 |
+| [Tool manifests in root folder](sdk/7.0/manifest-search.md) | ✔️ | ✔️ | 6.0.4xx, 6.0.3xx, 6.0.1xx |
 | [Version requirements for .NET 6 SDK](sdk/6.0/vs-msbuild-version.md) | ✔️ | ✔️ | 6.0.300 |
 | [.version file includes build version](sdk/6.0/version-file-entries.md) | ✔️ | ✔️ | 6.0.401 |
 | [Write reference assemblies to IntermediateOutputPath](sdk/6.0/write-reference-assemblies-to-obj.md) | ❌ | ✔️ | 6.0.200 |

docs/core/compatibility/7.0.md

@@ -2,7 +2,7 @@
 title: Breaking changes in .NET 7
 titleSuffix: ""
 description: Navigate to the breaking changes in .NET 7.
-ms.date: 05/18/2023
+ms.date: 07/28/2023
 no-loc: [Blazor, Razor, Kestrel]
 ---
 # Breaking changes in .NET 7
@@ -130,6 +130,7 @@ If you're migrating an app to .NET 7, the breaking changes listed here might aff
 | [Console encoding not UTF-8 after completion](sdk/8.0/console-encoding-fix.md) | ❌ | ✔️ |
 | [MSBuild serialization of custom types in .NET 7](sdk/7.0/custom-serialization.md) | ❌ | ❌ |
 | [Side-by-side SDK installations](sdk/7.0/side-by-side-install.md) | ❌ | ❌ |
+| [Tool manifests in root folder](sdk/7.0/manifest-search.md) | ✔️ | ✔️ |
 | [Version requirements for .NET 7 SDK](sdk/7.0/vs-msbuild-version.md) | ✔️ | ✔️ |
 | [dotnet test: switch `-a` to alias `--arch` instead of `--test-adapter-path`](https://github.com/dotnet/sdk/issues/21389) | ❌ | ❌ |
 | [dotnet test: switch `-r` to alias `--runtime` instead of `--results-dir`](https://github.com/dotnet/sdk/issues/21952) | ❌ | ❌ |

docs/core/compatibility/8.0.md

@@ -105,6 +105,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff
 | [.NET tool roll-forward behavior](sdk/8.0/tool-rollforward.md)                  | Behavioral change                                | Preview 5  |
 | [CLI console output uses UTF-8](sdk/8.0/console-encoding.md)                    | Behavioral change/Source and binary incompatible | Preview 1  |
 | [Console encoding not UTF-8 after completion](sdk/8.0/console-encoding-fix.md)  | Behavioral change/Binary incompatible            | Preview 3  |
+| [Containers default to use the 'latest' tag](sdk/8.0/default-image-tag.md) | Behavioral change | Preview 6 |
 | ['dotnet pack' uses Release configuration](sdk/8.0/dotnet-pack-config.md)       | Behavioral change/Source incompatible            | Preview 1  |
 | ['dotnet publish' uses Release configuration](sdk/8.0/dotnet-publish-config.md) | Behavioral change/Source incompatible            | Preview 1  |
 | [MSBuild respects DOTNET_CLI_UI_LANGUAGE](sdk/8.0/msbuild-language.md)          | Behavioral change                                | Preview 5  |

docs/core/compatibility/sdk/7.0/manifest-search.md

@@ -0,0 +1,41 @@
+---
+title: "Breaking change: Tool manifests in root folder"
+description: Learn about a breaking change where the .NET SDK no longer looks for local tool manifests in the root folder on Windows.
+ms.date: 07/28/2023
+---
+# Tool manifests in root folder
+
+.NET no longer looks for local tool manifest files in the root folder on Windows, unless overridden via the `DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT` environment variable. This change does not impact Linux or macOS.
+
+## Previous behavior
+
+Previously, .NET SDK local tools checked the root folder on all platforms when searching for a tool manifest. The search continued from the current directory up the directory tree to the root folder until it found a manifest. At each level, .NET searches for the tool manifest, named *dotnet-tools.json*, in a *.config* subfolder. On a Windows system, if no other tool manifest was found, the SDK ultimately looked for a tool manifest in *C:\\.config\dotnet-tools.json*.
+
+## New behavior
+
+.NET no longer searches in the root folder of the current directory tree by default on Windows, unless overridden via the `DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT` environment variable. `DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT` is set to `false` by default.
+
+## Version introduced
+
+- .NET SDK 7.0.3xx
+- .NET SDK 7.0.1xx
+- .NET SDK 6.0.4xx
+- .NET SDK 6.0.3xx
+- .NET SDK 6.0.1xx
+- .NET SDK 3.1.4xx
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change was made to address a security concern. Since all users can create files and folders in the *C:\\* directory on Windows, low-privilege attackers can hijack the *C:\\.config\dotnet-tools.json* file. When an administrator runs a `dotnet` tool command, the tool could potentially read malicious configuration information from the file and download and run malicious tools.
+
+## Recommended action
+
+To disable the new behavior, set the `DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT` environment variable to `true` or `1`.
+
+## See also
+
+- [Tutorial: Install and use a .NET local tool using the .NET CLI](../../../tools/local-tools-how-to-use.md)

docs/core/compatibility/sdk/8.0/default-image-tag.md

@@ -0,0 +1,42 @@
+---
+title: "Breaking change: Containers default to use the 'latest' tag"
+description: Learn about the breaking change in containers where .NET SDK-built containers default to use the 'latest' tag instead of '$(Version)'.
+ms.date: 07/27/2023
+---
+# Containers default to use the 'latest' tag
+
+The default image tag used for .NET SDK-built containers changed from the value of the `Version` of the project to the value `latest`.
+
+## Previous behavior
+
+Previously, the image was built with a tag value of `$(Version)`, which enabled changing the tag based on the same value that the rest of the .NET ecosystem uses.
+
+## New behavior
+
+Starting in .NET 8, the generated image has the `latest` tag in all cases.
+
+## Version introduced
+
+.NET 8 Preview 6
+
+## Type of change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change aligns the default containerization experience with the developer experiences for other container tooling like the Docker CLI. It also makes the development inner-loop of repeated container publishes easier to use with tools like Docker Compose, because the version remains stable.
+
+## Recommended action
+
+Explicitly set the version if you need it. The easiest way is to set the `ContainerImageTag` property on the command line to an explicit version, for example, `/p:ContainerImageTag=1.2.3`. But you can also programmatically set the value as you would any other MSBuild property. In a project file, you can continue to use the `$(Version)` property by adding the `ContainerImageTag` property:
+
+```xml
+<PropertyGroup>
+  <ContainerImageTag>$(Version)</ContainerImageTag>
+</PropertyGroup>
+```
+
+## Affected APIs
+
+None.

docs/core/compatibility/toc.yml

@@ -104,6 +104,8 @@ items:
         href: sdk/8.0/console-encoding.md
       - name: Console encoding not UTF-8 after completion
         href: sdk/8.0/console-encoding-fix.md
+      - name: Containers default to use the 'latest' tag
+        href: sdk/8.0/default-image-tag.md
       - name: "'dotnet pack' uses Release configuration"
         href: sdk/8.0/dotnet-pack-config.md
       - name: "'dotnet publish' uses Release configuration"
@@ -274,16 +276,18 @@ items:
         href: sdk/7.0/automatic-rid-publish-only.md
       - name: CLI console output uses UTF-8
         href: sdk/8.0/console-encoding.md
-      - name: Version requirements for .NET 7 SDK
+      - name: Version requirements
         href: sdk/7.0/vs-msbuild-version.md
       - name: SDK no longer calls ResolvePackageDependencies
         href: sdk/7.0/resolvepackagedependencies.md
-      - name: Serialization of custom types in .NET 7
+      - name: Serialization of custom types
         href: sdk/7.0/custom-serialization.md
       - name: Side-by-side SDK installations
         href: sdk/7.0/side-by-side-install.md
       - name: --output option no longer is valid for solution-level commands
         href: sdk/7.0/solution-level-output-no-longer-valid.md
+      - name: Tool manifests in root folder
+        href: sdk/7.0/manifest-search.md
     - name: Serialization
       items:
       - name: BinaryFormatter serialization APIs produce compiler errors
@@ -488,6 +492,8 @@ items:
         href: sdk/6.0/runtimeconfigdev-file.md
       - name: RuntimeIdentifier warning if self-contained is unspecified
         href: sdk/6.0/runtimeidentifier-self-contained.md
+      - name: Tool manifests in root folder
+        href: sdk/7.0/manifest-search.md
       - name: Version requirements for .NET 6 SDK
         href: sdk/6.0/vs-msbuild-version.md
       - name: .version file includes build version
@@ -1418,6 +1424,8 @@ items:
         href: sdk/8.0/console-encoding.md
       - name: Console encoding not UTF-8 after completion
         href: sdk/8.0/console-encoding-fix.md
+      - name: Containers default to use the 'latest' tag
+        href: sdk/8.0/default-image-tag.md
       - name: "'dotnet pack' uses Release configuration"
         href: sdk/8.0/dotnet-pack-config.md
       - name: "'dotnet publish' uses Release configuration"
@@ -1444,6 +1452,8 @@ items:
         href: sdk/7.0/side-by-side-install.md
       - name: --output option no longer is valid for solution-level commands
         href: sdk/7.0/solution-level-output-no-longer-valid.md
+      - name: Tool manifests in root folder
+        href: sdk/7.0/manifest-search.md
     - name: .NET 6
       items:
       - name: -p option for `dotnet run` is deprecated
@@ -1470,6 +1480,8 @@ items:
         href: sdk/6.0/runtimeconfigdev-file.md
       - name: RuntimeIdentifier warning if self-contained is unspecified
         href: sdk/6.0/runtimeidentifier-self-contained.md
+      - name: Tool manifests in root folder
+        href: sdk/7.0/manifest-search.md
       - name: Version requirements for .NET 6 SDK
         href: sdk/6.0/vs-msbuild-version.md
       - name: .version file includes build version

docs/core/deploying/trimming/prepare-libraries-for-trimming.md

@@ -50,7 +50,9 @@ To create your sample app, first create a separate console application project w
 - If your app targets .NET 7, [the new default behavior](../../../core/compatibility/deployment/7.0/trim-all-assemblies.md) is what you want, but you can enforce the behavior by adding `<TrimMode>full</TrimMode>` in a `<PropertyGroup>` tag.
   - This ensures that the trimmer only analyzes the parts of the library's dependencies that are used. It tells the trimmer that any code that isn't part of a "root" can be trimmed if it's unused. Without this option, you would see warnings originating from _any_ part of a dependency that doesn't set `[AssemblyMetadata("IsTrimmable", "True")]`, including parts that are unused by your library.
 
-##### .NET 6 .csproj
+##### .csproj file
+
+### [.NET 6](#tab/net6)
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
@@ -73,7 +75,7 @@ To create your sample app, first create a separate console application project w
 </Project>
 ```
 
-##### .NET 7 .csproj
+### [.NET 7](#tab/net7)
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
@@ -93,6 +95,28 @@ To create your sample app, first create a separate console application project w
 </Project>
 ```
 
+### [.NET 8+](#tab/net8plus)
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <PublishTrimmed>true</PublishTrimmed>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="path/to/MyLibrary.csproj" />
+    <!-- Analyze the whole library -->
+    <TrimmerRootAssembly Include="MyLibrary" />
+  </ItemGroup>
+
+</Project>
+```
+
+---
+
 Once your project file is updated, run `dotnet publish` with the [runtime identifier (RID)](../../rid-catalog.md) you want to target.
 
 ```dotnetcli
@@ -117,8 +141,8 @@ public class MyLibrary
 {
     public static void Method()
     {
-        // warning IL2026 : MyLibrary.Method: Using method 'MyLibrary.DynamicBehavior' which has
-        // 'RequiresUnreferencedCodeAttribute' can break functionality
+        // warning IL2026 : MyLibrary.Method: Using method 'MyLibrary.DynamicBehavior'
+        //  which has 'RequiresUnreferencedCodeAttribute' can break functionality
         // when trimming application code.
         DynamicBehavior();
     }
@@ -154,8 +178,10 @@ public class MyLibrary
     static void UseMethods(Type type)
     {
         // warning IL2070: MyLibrary.UseMethods(Type): 'this' argument does not satisfy
-        // 'DynamicallyAccessedMemberTypes.PublicMethods' in call to 'System.Type.GetMethods()'.
-        // The parameter 't' of method 'MyLibrary.UseMethods(Type)' does not have matching annotations.
+        // 'DynamicallyAccessedMemberTypes.PublicMethods' in call to
+        // 'System.Type.GetMethods()'.
+        // The parameter 't' of method 'MyLibrary.UseMethods(Type)' doesn't have
+        // matching annotations.
         foreach (var method in type.GetMethods())
         {
             // ...
@@ -186,7 +212,8 @@ static Type type;
 static void UseMethodsHelper()
 {
     // warning IL2077: MyLibrary.UseMethodsHelper(Type): 'type' argument does not satisfy
-    // 'DynamicallyAccessedMemberTypes.PublicMethods' in call to 'MyLibrary.UseMethods(Type)'.
+    // 'DynamicallyAccessedMemberTypes.PublicMethods' in call to
+    // 'MyLibrary.UseMethods(Type)'.
     // The field 'System.Type MyLibrary::type' does not have matching annotations.
     UseMethods(type);
 }

docs/core/tools/dotnet-environment-variables.md

@@ -8,7 +8,7 @@ ms.date: 04/04/2023
 
 **This article applies to:** ✔️ .NET Core 3.1 SDK and later versions
 
-In this article, you'll learn about the environment variables used by .NET SDK, .NET CLI, and .NET runtime. Some environment variables are used by the .NET runtime, while others are only used by the .NET SDK and .NET CLI. Some environment variables are used by all.
+In this article, you'll learn about the environment variables used by .NET. Some environment variables are used by the .NET runtime, while others are only used by the .NET SDK and .NET CLI. Some environment variables are used by all three components.
 
 ## .NET runtime environment variables
 
@@ -287,7 +287,11 @@ Disables background download of advertising manifests for workloads. Default is
 
 ### `DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS`
 
-Specifies the minimum number of hours between background downloads of advertising manifests for workloads. Default is `24` - no more frequently than once a day. For more information, see [Advertising manifests](dotnet-workload-install.md#advertising-manifests).
+Specifies the minimum number of hours between background downloads of advertising manifests for workloads. The default is `24`, which is no more frequently than once a day. For more information, see [Advertising manifests](dotnet-workload-install.md#advertising-manifests).
+
+### `DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT`
+
+Specifies whether .NET SDK local tools search for tool manifest files in the root folder on Windows. The default is `false`.
 
 ### `COREHOST_TRACE`
 

docs/core/whats-new/dotnet-8.md

@@ -1086,6 +1086,7 @@ Building in a container is the easiest approach for most people, since the `dotn
 | [CA1859](../../fundamentals/code-analysis/quality-rules/ca1859.md) | Performance | This rule recommends upgrading the type of specific local variables, fields, properties, method parameters, and method return types from interface or abstract types to concrete types when possible. Using concrete types leads to higher quality generated code. |
 | [CA1860](../../fundamentals/code-analysis/quality-rules/ca1860.md) | Performance | To determine whether a collection type has any elements, it's better to use `Length`, `Count`, or `IsEmpty` than to call <xref:System.Linq.Enumerable.Any%2A?displayProperty=nameWithType>. |
 | [CA1861](../../fundamentals/code-analysis/quality-rules/ca1861.md) | Performance | Constant arrays passed as arguments aren't reused when called repeatedly, which implies a new array is created each time. To improve performance, consider extracting the array to a static readonly field. |
+| [CA1865-CA1867](../../fundamentals/code-analysis/quality-rules/ca1865-ca1867.md) | Performance | The char overload is a better performing overload for a string with a single char. |
 | CA2021 | Reliability | <xref:System.Linq.Enumerable.Cast%60%601(System.Collections.IEnumerable)?displayProperty=nameWithType> and <xref:System.Linq.Enumerable.OfType%60%601(System.Collections.IEnumerable)?displayProperty=nameWithType> require compatible types to function correctly. Widening and user-defined conversions aren't supported with generic types. |
 | CA1510-CA1513 | Maintainability | Throw helpers are simpler and more efficient than an `if` block constructing a new exception instance. These four analyzers were created for the following exceptions: <xref:System.ArgumentNullException>, <xref:System.ArgumentException>, <xref:System.ArgumentOutOfRangeException> and <xref:System.ObjectDisposedException>. |