diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index f988fbe394f8c..7810fceda92c7 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -254,7 +254,7 @@ | Resource Management - Compute Bulk Actions | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ComputeBulkActions/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeBulkActions_1.0.0-beta.1/sdk/computebulkactions/Azure.ResourceManager.ComputeBulkActions/) | | Resource Management - Compute Fleet | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ComputeFleet/1.0.0)
NuGet [1.1.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.ComputeFleet/1.1.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.ComputeFleet-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeFleet_1.0.0/sdk/computefleet/Azure.ResourceManager.ComputeFleet/)
GitHub [1.1.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeFleet_1.1.0-beta.3/sdk/computefleet/Azure.ResourceManager.ComputeFleet/) | | Resource Management - Compute Limit | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ComputeLimit/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ComputeLimit-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeLimit_1.4.0/sdk/computelimit/Azure.ResourceManager.ComputeLimit/) | -| Resource Management - Compute Recommender | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute.Recommender-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.0.0/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.1.0-beta.1/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/) | +| Resource Management - Compute Recommender | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.0.0)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute.Recommender-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.0.0/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.1.0-beta.2/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/) | | Resource Management - Compute Schedule | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ComputeSchedule/1.1.0)
NuGet [1.2.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.ComputeSchedule/1.2.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ComputeSchedule-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeSchedule_1.1.0/sdk/computeschedule/Azure.ResourceManager.ComputeSchedule/)
GitHub [1.2.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeSchedule_1.2.0-beta.5/sdk/computeschedule/Azure.ResourceManager.ComputeSchedule/) | | Resource Management - Confidential Ledger | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ConfidentialLedger/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ConfidentialLedger-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ConfidentialLedger_1.1.0/sdk/confidentialledger/Azure.ResourceManager.ConfidentialLedger/) | | Resource Management - Confluent | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.Confluent/1.2.1)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Confluent/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Confluent-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Confluent_1.2.1/sdk/confluent/Azure.ResourceManager.Confluent/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Confluent_1.3.0-beta.1/sdk/confluent/Azure.ResourceManager.Confluent/) | @@ -469,13 +469,13 @@ | App Configuration Provider | NuGet [8.6.0](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore/8.6.0)
NuGet [8.7.0-preview](https://www.nuget.org/packages/Microsoft.Azure.AppConfiguration.AspNetCore/8.7.0-preview) | | | | Azure Functions CLI | NuGet [5.0.0-preview.1](https://www.nuget.org/packages/Azure.Functions.Cli.Abstractions/5.0.0-preview.1) | | | | Azure Functions SDK | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Functions.Sdk/1.0.0) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp/3.0.0-beta.40) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/3.0.0-beta.40) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp.linux-x64/3.0.0-beta.40) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/3.0.0-beta.40) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-x64/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp.osx-x64/3.0.0-beta.40) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-arm64/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp.win-arm64/3.0.0-beta.40) | | | -| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-x64/1.0.0)
NuGet [3.0.0-beta.40](https://www.nuget.org/packages/Azure.Mcp.win-x64/3.0.0-beta.40) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp/3.0.0-beta.41) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/3.0.0-beta.41) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp.linux-x64/3.0.0-beta.41) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp.osx-arm64/3.0.0-beta.41) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.osx-x64/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp.osx-x64/3.0.0-beta.41) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-arm64/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp.win-arm64/3.0.0-beta.41) | | | +| Azure MCP | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.win-x64/1.0.0)
NuGet [3.0.0-beta.41](https://www.nuget.org/packages/Azure.Mcp.win-x64/3.0.0-beta.41) | | | | Azure MCP Types Internal | NuGet [0.2.804](https://www.nuget.org/packages/Microsoft.Azure.Mcp.AzTypes.Internal.Compact/0.2.804) | | | | Azure.Communication.Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | | | | Caching - PostgreSQL | NuGet [1.2.2](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Postgres/1.2.2) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 9df04e134f11d..ce9e986be3eed 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -270,7 +270,7 @@ | Resource Management - Compute Bulk Actions | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ComputeBulkActions/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeBulkActions_1.0.0-beta.1/sdk/computebulkactions/Azure.ResourceManager.ComputeBulkActions/) | | Resource Management - Compute Fleet | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ComputeFleet/1.0.0)
NuGet [1.1.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.ComputeFleet/1.1.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.ComputeFleet-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeFleet_1.0.0/sdk/computefleet/Azure.ResourceManager.ComputeFleet/)
GitHub [1.1.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeFleet_1.1.0-beta.3/sdk/computefleet/Azure.ResourceManager.ComputeFleet/) | | Resource Management - Compute Limit | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ComputeLimit/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ComputeLimit-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeLimit_1.4.0/sdk/computelimit/Azure.ResourceManager.ComputeLimit/) | -| Resource Management - Compute Recommender | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute.Recommender-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.0.0/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.1.0-beta.1/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/) | +| Resource Management - Compute Recommender | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.0.0)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Compute.Recommender/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Compute.Recommender-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.0.0/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Compute.Recommender_1.1.0-beta.2/sdk/computerecommender/Azure.ResourceManager.Compute.Recommender/) | | Resource Management - Compute Schedule | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ComputeSchedule/1.1.0)
NuGet [1.2.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.ComputeSchedule/1.2.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ComputeSchedule-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeSchedule_1.1.0/sdk/computeschedule/Azure.ResourceManager.ComputeSchedule/)
GitHub [1.2.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ComputeSchedule_1.2.0-beta.5/sdk/computeschedule/Azure.ResourceManager.ComputeSchedule/) | | Resource Management - Confidential Ledger | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ConfidentialLedger/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ConfidentialLedger-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ConfidentialLedger_1.1.0/sdk/confidentialledger/Azure.ResourceManager.ConfidentialLedger/) | | Resource Management - Confluent | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.Confluent/1.2.1)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Confluent/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Confluent-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Confluent_1.2.1/sdk/confluent/Azure.ResourceManager.Confluent/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Confluent_1.3.0-beta.1/sdk/confluent/Azure.ResourceManager.Confluent/) | diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index ac2c77d9bbac3..2ba79f955a4ae 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -111,6 +111,7 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- | [NativeAOT CLI command handling enabled by default](sdk/11/native-cli-command-handling-enabled.md) | Behavioral change | | [NU1703 warns for packages that use deprecated MonoAndroid framework assets](sdk/11/nu1703-deprecated-monoandroid-framework.md) | Source incompatible | | [NuGet pack warns for package IDs with restricted characters](sdk/11/nuget-pack-nu5052-packageid.md) | Behavioral change | +| [Restore doesn't search global packages folder for higher version](sdk/11/restore-global-packages-folder-version-search.md) | Source incompatible | | [SDK local container runtime selection prefers platform-native tools](sdk/11/native-local-container-runtimes.md) | Behavioral change | | [Template engine packages no longer support netstandard2.0](sdk/11/template-engine-netstandard.md) | Binary/source incompatible | | [VSTest removes dependency on Newtonsoft.Json](sdk/11/vstest-removes-newtonsoft-json.md) | Binary/source incompatible | diff --git a/docs/core/compatibility/sdk/11/restore-global-packages-folder-version-search.md b/docs/core/compatibility/sdk/11/restore-global-packages-folder-version-search.md new file mode 100644 index 0000000000000..10f30ea144240 --- /dev/null +++ b/docs/core/compatibility/sdk/11/restore-global-packages-folder-version-search.md @@ -0,0 +1,52 @@ +--- +title: "Breaking change: Restore doesn't search the global packages folder for a higher package version" +description: "Learn about the breaking change in .NET 11 where NuGet restore no longer considers versions in the global packages folder when it selects a higher package version." +ms.date: 09/01/2026 +ai-usage: ai-assisted +--- + +# Restore doesn't search the global packages folder for a higher package version + +When a `PackageReference` or package dependency requests a package version that doesn't exist, NuGet restore searches for the lowest version that's higher than the requested version. NuGet restore no longer includes the versions in the global packages folder in that search. + +## Version introduced + +.NET 11 RC 1 + +## Previous behavior + +Previously, when restore couldn't find the requested version, it searched both the package sources and the global packages folder for the "next best" version, that is, the lowest version that's higher than the requested version. Restore selected that version and raised an [NU1603](/nuget/reference/errors-and-warnings/nu1603) warning. If no higher version was found, restore reported an NU1102 error. + +| Package source | Global packages folder | Requested version | Version selected | Restore outcome | +|----------------|------------------------|-------------------|------------------|-----------------| +| 1.0.0, 2.0.0 | 1.5.0 | 1.1.0 | 1.5.0 | NU1603 warning | +| 1.0.0 | 1.5.0 | 1.1.0 | 1.5.0 | NU1603 warning | + +## New behavior + +Starting in .NET 11, restore searches only the package sources for the "next best" version. Because the global packages folder is excluded from the search, restore might select a higher version than before, or fail with an [NU1102 error](/nuget/reference/errors-and-warnings/nu1102) if no package source has a higher version. + +| Package source | Global packages folder | Requested version | Version selected | Restore outcome | +|----------------|------------------------|-------------------|------------------|-----------------| +| 1.0.0, 2.0.0 | 1.5.0 | 1.1.0 | 2.0.0 | NU1603 warning | +| 1.0.0 | 1.5.0 | 1.1.0 | n/a | NU1102 error | + +If the global packages folder contains the exact requested version, restore uses that version, even if no package source has that version. This behavior is unchanged. + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +Restore is now more deterministic and repeatable. For performance reasons, NuGet doesn't validate that packages in the global packages folder match the packages on the package sources. However, restore now selects the same package version on different computers, where the global packages folder might contain different versions. + +## Recommended action + +Reference only package versions that exist on your package sources. This practice ensures that the version selected during restore doesn't change over time as new versions are published to the package sources. + +For more information, see [Best practices for a secure software supply chain](/nuget/concepts/security-best-practices). + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index f7ed617a0b231..8f456b413717f 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -104,6 +104,8 @@ items: href: sdk/11/nu1703-deprecated-monoandroid-framework.md - name: NuGet pack warns for package IDs with restricted characters href: sdk/11/nuget-pack-nu5052-packageid.md + - name: Restore doesn't search global packages folder for higher version + href: sdk/11/restore-global-packages-folder-version-search.md - name: SDK local container runtime selection prefers platform-native tools href: sdk/11/native-local-container-runtimes.md - name: Template engine packages no longer support netstandard2.0 diff --git a/docs/core/diagnostics/built-in-metrics-diagnostics.md b/docs/core/diagnostics/built-in-metrics-diagnostics.md index 835ffc0414411..af716f1e9d99b 100644 --- a/docs/core/diagnostics/built-in-metrics-diagnostics.md +++ b/docs/core/diagnostics/built-in-metrics-diagnostics.md @@ -71,13 +71,14 @@ The `Microsoft.Extensions.Diagnostics.ResourceMonitoring` metrics report resourc - [`container.cpu.request.utilization`](#metric-containercpurequestutilization) - [`container.cpu.time`](#metric-containercputime) - [`container.memory.limit.utilization`](#metric-containermemorylimitutilization) +- [`container.memory.request.utilization`](#metric-containermemoryrequestutilization) - [`container.memory.usage`](#metric-containermemoryusage) - [`process.cpu.utilization`](#metric-processcpuutilization) - [`dotnet.process.memory.virtual.utilization`](#metric-dotnetprocessmemoryvirtualutilization) - [`system.network.connections`](#metric-systemnetworkconnections) > [!NOTE] -> Metrics emitted by the `Microsoft.Extensions.Diagnostics.ResourceMonitoring` meter are in experimental stage. This means that there could be breaking changes to them. +> Some metrics emitted by the `Microsoft.Extensions.Diagnostics.ResourceMonitoring` meter (such as disk I/O) are in experimental stage and not documented here. ##### Metric: `container.cpu.limit.utilization` @@ -85,17 +86,17 @@ The instrument is only available on a system running on containers both on Windo | Name | Instrument Type | Unit (UCUM) | Description | | ---- | --------------- | ----------- | ----------- | -| `container.cpu.limit.utilization` | | `1` | The CPU consumption of the running containerized application relative to resource limit in range `[0, 1]`. | +| `container.cpu.limit.utilization` | | `1` | The CPU consumption of the running containerized application relative to resource limit. Linux: range `[0, 1]` by default. Windows: range `[0, 100]` by default. See `UseZeroToOneRangeForMetrics` and `UseZeroToOneRangeForLinuxMetrics` options to change the default behavior. | Available starting in `Microsoft.Extensions.Diagnostics.ResourceMonitoring` 8.8.0. ##### Metric: `container.cpu.request.utilization` -The instrument is only available on a system running on containers on Linux. +The instrument is only available on a system running on containers both on Windows and Linux. | Name | Instrument Type | Unit (UCUM) | Description | | ---- | --------------- | ----------- | ----------- | -| `container.cpu.request.utilization` | | `1` | The CPU consumption of the running containerized application relative to resource request in range `[0, 1]`. | +| `container.cpu.request.utilization` | | `1` | The CPU consumption of the running containerized application relative to resource request. Linux: range `[0, 1]` by default. Windows: range `[0, 100]` by default. See `UseZeroToOneRangeForMetrics` and `UseZeroToOneRangeForLinuxMetrics` options to change the default behavior. | Available starting in `Microsoft.Extensions.Diagnostics.ResourceMonitoring` 8.8.0. @@ -115,10 +116,20 @@ The instrument is only available on a system running on containers both on Windo | Name | Instrument Type | Unit (UCUM) | Description | | ---- | --------------- | ----------- | ----------- | -| `container.memory.limit.utilization` | | `1` | The memory consumption of the running containerized application relative to resource limit in range `[0, 1]`. | +| `container.memory.limit.utilization` | | `1` | The memory consumption of the running containerized application relative to resource limit. Linux: range `[0, 1]` by default. Windows: range `[0, 100]` by default. See `UseZeroToOneRangeForMetrics` and `UseZeroToOneRangeForLinuxMetrics` options to change the default behavior. | Available starting in `Microsoft.Extensions.Diagnostics.ResourceMonitoring` 8.8.0. +##### Metric: `container.memory.request.utilization` + +The instrument is only available on a system running on containers both on Windows and Linux. + +| Name | Instrument Type | Unit (UCUM) | Description | +| ---- | --------------- | ----------- | ----------- | +| `container.memory.request.utilization` | | `1` | The memory consumption of the running containerized application relative to resource request. Linux: range `[0, 1]` by default. Windows: range `[0, 100]` by default. See `UseZeroToOneRangeForMetrics` and `UseZeroToOneRangeForLinuxMetrics` options to change the default behavior. | + +Available starting in `Microsoft.Extensions.Diagnostics.ResourceMonitoring` 9.8.0. + ##### Metric: `container.memory.usage` The instrument is only available on a system running on containers either on Windows or Linux. @@ -133,7 +144,7 @@ Available starting in `Microsoft.Extensions.Diagnostics.ResourceMonitoring` 9.8. | Name | Instrument Type | Unit (UCUM) | Description | | ---- | --------------- | ----------- | ----------- | -| `process.cpu.utilization` | | `1` | The CPU consumption of the running application in range `[0, 1]`. | +| `process.cpu.utilization` | | `1` | The CPU consumption of the running application. Linux: range `[0, 1]` by default. Windows: range `[0, 100]` by default. See `UseZeroToOneRangeForMetrics` and `UseZeroToOneRangeForLinuxMetrics` options to change the default behavior. | Available starting in: .NET 8. @@ -141,7 +152,7 @@ Available starting in: .NET 8. | Name | Instrument Type | Unit (UCUM) | Description | | ---- | --------------- | ----------- | ----------- | -| `dotnet.process.memory.virtual.utilization` | | `1` | The memory consumption of the running application in range `[0, 1]`. | +| `dotnet.process.memory.virtual.utilization` | | `1` | The memory consumption of the running application. Linux: range `[0, 1]` by default. Windows: range `[0, 100]` by default. See `UseZeroToOneRangeForMetrics` and `UseZeroToOneRangeForLinuxMetrics` options to change the default behavior. | Available starting in: .NET 8. diff --git a/docs/core/diagnostics/diagnostic-resource-monitoring.md b/docs/core/diagnostics/diagnostic-resource-monitoring.md index 45a6c04b220e2..8496ddfc5e9b4 100644 --- a/docs/core/diagnostics/diagnostic-resource-monitoring.md +++ b/docs/core/diagnostics/diagnostic-resource-monitoring.md @@ -98,8 +98,9 @@ For the source code of this example, see the [Resource monitoring sample](https: Since the interface is deprecated, migrate to the metrics-based approach. The `Microsoft.Extensions.Diagnostics.ResourceMonitoring` package provides several metrics that you can use instead, for instance: - `container.cpu.limit.utilization`: The CPU consumption share of the running containerized application relative to resource limit in range `[0, 1]`. Available for containerized apps on Linux and Windows. -- `container.cpu.request.utilization`: The CPU consumption share of the running containerized application relative to resource request in range `[0, 1]`. Available for containerized apps on Linux. +- `container.cpu.request.utilization`: The CPU consumption share of the running containerized application relative to resource request in range `[0, 1]`. Available for containerized apps on Linux and Windows. - `container.memory.limit.utilization`: The memory consumption share of the running containerized application relative to resource limit in range `[0, 1]`. Available for containerized apps on Linux and Windows. +- `container.memory.request.utilization`: The memory consumption share of the running containerized application relative to resource request in range `[0, 1]`. Available for containerized apps on Linux and Windows. For more information about the available metrics, see the [Built-in metrics: Microsoft.Extensions.Diagnostics.ResourceMonitoring](built-in-metrics-diagnostics.md#microsoftextensionsdiagnosticsresourcemonitoring) section. @@ -124,6 +125,176 @@ The following is an example of the output from the preceding code: For the complete source code of this example, see the [Resource monitoring with manual metrics sample](https://github.com/dotnet/docs/tree/main/docs/core/diagnostics/snippets/resource-monitoring-with-manual-metrics). +## Kubernetes resource monitoring + +When your application runs inside a Kubernetes cluster, you typically configure resource limits and requests in your pod specification. The [Microsoft.Extensions.Diagnostics.ResourceMonitoring.Kubernetes](https://www.nuget.org/packages/Microsoft.Extensions.Diagnostics.ResourceMonitoring.Kubernetes) NuGet package extends the base resource monitoring library to read these values from environment variables exposed by the [Kubernetes Downward API](https://kubernetes.io/docs/concepts/workloads/pods/downward-api/). + +This package automatically detects your container's CPU and memory boundaries and emits accurate utilization metrics relative to those values. + +> [!TIP] +> If your cluster runs Kubernetes v1.32 or later with cgroup v2, always prefer `AddKubernetesResourceMonitoring()` over `AddResourceMonitoring()` for accurate request-based utilization metrics. The Kubernetes package reads CPU and memory requests directly from environment variables, bypassing the cgroup weight inversion that can produce inaccurate values. See [Known limitations](#known-limitations-on-cgroup-v2) for details. + +### How it works + +The Kubernetes Downward API can expose pod resource limits and requests as environment variables. The `Microsoft.Extensions.Diagnostics.ResourceMonitoring.Kubernetes` package reads these environment variables at startup and uses them to calculate utilization metrics. + +You choose a prefix for your environment variables (for example, `MY_APP_`). The library then looks for the following variables: + +| Environment variable | Description | +| --- | --- | +| `LIMITS_CPU` | CPU limit in millicores (for example, `2000` for 2 cores) | +| `LIMITS_MEMORY` | Memory limit in bytes | +| `REQUESTS_CPU` | CPU request in millicores (optional, defaults to limit value) | +| `REQUESTS_MEMORY` | Memory request in bytes (optional, defaults to limit value) | + +At minimum, you must set `LIMITS_CPU` and `LIMITS_MEMORY` to non-zero values. If you omit the request variables or set them to zero, the library defaults them to the corresponding limit values. + +### Configure the Downward API + +To expose resource limits as environment variables, add `resourceFieldRef` entries to your Kubernetes deployment manifest: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app +spec: + template: + spec: + containers: + - name: my-app + resources: + requests: + cpu: "500m" + memory: "256Mi" + limits: + cpu: "1000m" + memory: "512Mi" + env: + - name: MY_APP_LIMITS_CPU + valueFrom: + resourceFieldRef: + resource: limits.cpu + divisor: "1m" + - name: MY_APP_LIMITS_MEMORY + valueFrom: + resourceFieldRef: + resource: limits.memory + divisor: "1" + - name: MY_APP_REQUESTS_CPU + valueFrom: + resourceFieldRef: + resource: requests.cpu + divisor: "1m" + - name: MY_APP_REQUESTS_MEMORY + valueFrom: + resourceFieldRef: + resource: requests.memory + divisor: "1" +``` + +The `divisor: "1m"` for CPU fields ensures Kubernetes expresses the value in millicores (for example, a `500m` limit becomes `500`). The `divisor: "1"` for memory fields returns the value in bytes. + +### Register Kubernetes resource monitoring + +In your application code, call with the environment variable prefix that matches your Kubernetes manifest: + +:::code source="snippets/resource-monitoring-kubernetes/Program.cs"::: + +The `"MY_APP_"` prefix tells the library to look for environment variables named `MY_APP_LIMITS_CPU`, `MY_APP_LIMITS_MEMORY`, `MY_APP_REQUESTS_CPU`, and `MY_APP_REQUESTS_MEMORY`. + +> [!IMPORTANT] +> Don't call `AddResourceMonitoring()` in addition to `AddKubernetesResourceMonitoring()`. The Kubernetes method already registers all necessary base resource monitoring components. Calling both methods can result in conflicting service registrations. + +### Emitted metrics + +Once registered, the library emits the following metrics under the `Microsoft.Extensions.Diagnostics.ResourceMonitoring` meter. It uses the Kubernetes resource boundaries you configured for its calculations: + +| Metric name | Type | Description | +| --- | --- | --- | +| `container.cpu.limit.utilization` | ObservableGauge | CPU usage relative to the configured limit, in the range [0, 1] | +| `container.cpu.request.utilization` | ObservableGauge | CPU usage relative to the configured request, in the range [0, 1] | +| `container.cpu.time` | ObservableCounter | Total CPU time consumed in seconds, with a `cpu.mode` dimension (user/system) | +| `container.memory.limit.utilization` | ObservableGauge | Memory usage relative to the configured limit, in the range [0, 1] | +| `container.memory.request.utilization` | ObservableGauge | Memory usage relative to the configured request, in the range [0, 1] | +| `container.memory.usage` | ObservableUpDownCounter | Memory usage in bytes | +| `process.cpu.utilization` | ObservableGauge | Process CPU usage relative to the CPU limit, in the range [0, 1] | +| `dotnet.process.memory.virtual.utilization` | ObservableGauge | Process memory usage relative to the memory limit, in the range [0, 1] | + +For the full list of metrics emitted by the base resource monitoring library, see [.NET extensions metrics: Microsoft.Extensions.Diagnostics.ResourceMonitoring](built-in-metrics-diagnostics.md#microsoftextensionsdiagnosticsresourcemonitoring). + +### Example output + +When you run your application inside a Kubernetes pod with the environment variables configured, the metrics produce values such as: + +``` +Instrument: container.cpu.limit.utilization + Value: 0.23 + +Instrument: container.cpu.request.utilization + Value: 0.46 + +Instrument: container.memory.limit.utilization + Value: 0.61 + +Instrument: container.memory.request.utilization + Value: 0.78 + +Instrument: container.memory.usage + Value: 312475648 (By) + +Instrument: container.cpu.time + Value: 142.35 (s), cpu.mode=user + Value: 28.91 (s), cpu.mode=system +``` + +In this example, the pod uses 23% of its CPU limit and 61% of its memory limit. Because the CPU request is lower than the CPU limit, `container.cpu.request.utilization` shows a higher value (46%) for the same absolute CPU usage. + +### Collect metrics with OpenTelemetry + +To export these metrics to your observability backend, register the meter with OpenTelemetry: + +```csharp +services.AddOpenTelemetry() + .WithMetrics(builder => + { + builder.AddMeter("Microsoft.Extensions.Diagnostics.ResourceMonitoring"); + builder.AddOtlpExporter(); // Or any other metrics exporter + }); +``` + +### Known limitations on cgroup v2 + +Starting with Kubernetes v1.32 (using runc 1.3.2+ or crun 1.23+), the OCI runtime uses a new quadratic formula to convert cgroup v1 CPU shares to cgroup v2 CPU weight. This change affects the accuracy of the base `AddResourceMonitoring()` method when it attempts to derive CPU request values from cgroup parameters on Linux. + +The core issue is that the base resource monitoring library reads `cpu.weight` from the cgroup v2 filesystem and reverse-converts it to estimate the original CPU request in millicores. However, the new conversion formula is **many-to-one**: multiple milliCPU values map to the same `cpu.weight`. For example, milliCPU values from 90 through 109 all produce `cpu.weight = 17`. Reversing this mapping cannot recover the exact original value, which means `container.cpu.request.utilization` may report inaccurate values. + +The following metrics are affected: + +| Metric | Affected? | Reason | +| --- | --- | --- | +| `container.cpu.request.utilization` | Yes | Relies on inferred CPU request from `cpu.weight` | +| `container.memory.request.utilization` | Yes | Relies on inferred memory request from cgroup parameters | +| `container.cpu.limit.utilization` | No | Uses `cpu.max`, not `cpu.weight` | +| `container.memory.limit.utilization` | No | Uses memory limit directly from cgroup | + +**How the Kubernetes package solves this:** `AddKubernetesResourceMonitoring()` reads the actual CPU and memory request values directly from environment variables you configure through the Downward API. It never reverse-converts cgroup parameters, so utilization metrics are always accurate regardless of which OCI runtime conversion formula your cluster uses. + +For more information, see: + +- [New cgroup v1 to v2 CPU conversion formula (Kubernetes blog)](https://kubernetes.io/blog/2026/01/30/new-cgroup-v1-to-v2-cpu-conversion-formula/) +- [dotnet/extensions issue #7202](https://github.com/dotnet/extensions/issues/7202) + +### Best practices + +When deploying .NET applications to Kubernetes, consider the following recommendations: + +- **Use the Kubernetes package in Kubernetes environments.** Always prefer `AddKubernetesResourceMonitoring()` over `AddResourceMonitoring()` when running in a Kubernetes cluster. It provides accurate resource utilization metrics by reading CPU and memory request values directly from environment variables rather than inferring them from cgroup parameters. + +- **Expose resource metadata through the Downward API.** Configure your deployment manifests to expose CPU and memory limits and requests as environment variables. This ensures the library has access to the exact values you specified in your pod spec. + +- **Test metric accuracy after cluster upgrades.** When upgrading your Kubernetes cluster or OCI runtime (runc, crun), verify that your resource utilization metrics still report expected values, especially if you use the base `AddResourceMonitoring()` method. + ## Kubernetes probes In addition to resource monitoring, apps that exist within a Kubernetes cluster report their health through diagnostic probes. The [Microsoft.Extensions.Diagnostics.Probes](https://www.nuget.org/packages/Microsoft.Extensions.Diagnostics.Probes) NuGet package provides support for Kubernetes probes. It externalizes various [health checks](diagnostic-health-checks.md) that align with various Kubernetes probes, for example: diff --git a/docs/core/diagnostics/snippets/resource-monitoring-kubernetes/Program.cs b/docs/core/diagnostics/snippets/resource-monitoring-kubernetes/Program.cs new file mode 100644 index 0000000000000..ca8cea347f2b5 --- /dev/null +++ b/docs/core/diagnostics/snippets/resource-monitoring-kubernetes/Program.cs @@ -0,0 +1,11 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; + +var app = Host.CreateDefaultBuilder() + .ConfigureServices(services => + { + services.AddKubernetesResourceMonitoring("MY_APP_"); + }) + .Build(); + +await app.RunAsync(); diff --git a/docs/core/diagnostics/snippets/resource-monitoring-kubernetes/resource-monitoring-kubernetes.csproj b/docs/core/diagnostics/snippets/resource-monitoring-kubernetes/resource-monitoring-kubernetes.csproj new file mode 100644 index 0000000000000..7a3f0875540a8 --- /dev/null +++ b/docs/core/diagnostics/snippets/resource-monitoring-kubernetes/resource-monitoring-kubernetes.csproj @@ -0,0 +1,17 @@ + + + + Exe + net10.0 + enable + enable + + + + + + + + + + diff --git a/docs/core/sdk/file-based-apps.md b/docs/core/sdk/file-based-apps.md index d533f287c7428..38dbd6e51908c 100644 --- a/docs/core/sdk/file-based-apps.md +++ b/docs/core/sdk/file-based-apps.md @@ -1,7 +1,7 @@ --- title: File-based apps description: Learn how to create, build, and run C# applications from a single file without a project file. -ms.date: 04/22/2026 +ms.date: 08/31/2026 ai-usage: ai-assisted --- # File-based apps @@ -277,6 +277,8 @@ For more information, see [Safe storage of app secrets in development](/aspnet/c File-based apps support launch profiles for configuring how the application runs during development. Instead of placing launch profiles in `Properties/launchSettings.json`, file-based apps can use a flat launch settings file named `[ApplicationName].run.json` in the same directory as the source file. +For the general profile format and properties that `dotnet run` supports, see [Launch profiles](../tools/dotnet-run.md#launch-profiles). + ### Flat launch settings file Create a launch settings file named after your application. For example, if your file-based app is `app.cs`, create `app.run.json` in the same directory: diff --git a/docs/core/tools/dotnet-environment-variables.md b/docs/core/tools/dotnet-environment-variables.md index 3abd2791da0c0..ef0f94e0dac0d 100644 --- a/docs/core/tools/dotnet-environment-variables.md +++ b/docs/core/tools/dotnet-environment-variables.md @@ -252,7 +252,7 @@ Starting in Visual Studio 2026, MSBuild in Visual Studio _also_ ensures that `DO ### `DOTNET_LAUNCH_PROFILE` -The [dotnet run](dotnet-run.md) command sets this variable to the selected launch profile. +The [`dotnet run` command](dotnet-run.md#launch-profiles) sets this variable to the selected launch profile. Given the following _launchSettings.json_ file: diff --git a/docs/core/tools/dotnet-run.md b/docs/core/tools/dotnet-run.md index 62d77bde2a3ef..80cffc8b4f659 100644 --- a/docs/core/tools/dotnet-run.md +++ b/docs/core/tools/dotnet-run.md @@ -1,7 +1,8 @@ --- title: dotnet run command description: The dotnet run command provides a convenient option to run your application from the source code. -ms.date: 06/05/2026 +ms.date: 09/04/2026 +ai-usage: ai-assisted --- # dotnet run @@ -53,6 +54,112 @@ To run the application, the `dotnet run` command resolves the dependencies of th [!INCLUDE [cli-advertising-manifests](includes/cli-advertising-manifests.md)] +## Launch profiles + +Launch profiles configure how `dotnet run` starts an app during development. For an SDK-style project, put the settings in `Properties/launchSettings.json`. Visual Basic projects use `My Project/launchSettings.json` instead. + +File-based apps can use an `[ApplicationName].run.json` file next to the source file. For the file lookup order and examples, see [Launch profiles for file-based apps](../sdk/file-based-apps.md#launch-profiles). + +The launch settings file contains a top-level `profiles` object. Each property in `profiles` defines a named profile: + +```json +{ + "profiles": { + "Local": { + "commandName": "Project", + "commandLineArgs": "--input sample.txt", + "dotnetRunMessages": true, + "environmentVariables": { + "APP_MODE": "local" + } + } + } +} +``` + +The .NET SDK launch settings parser accepts JSON comments and trailing commas. + +### Select a profile + +Use `--launch-profile ` to select a named profile. The name match is case-insensitive. Profile names that differ only by case are ambiguous and produce an error. + +If you don't specify a name, `dotnet run` selects the first profile in file order whose `commandName` it supports. Use `--no-launch-profile` to skip the launch settings file. + +When `dotnet run` applies a profile, it sets [`DOTNET_LAUNCH_PROFILE`](dotnet-environment-variables.md#dotnet_launch_profile) to the selected profile name in the launched process. A later environment-variable source can override the value. + +### Supported profile types + +The .NET SDK supports these `commandName` values for `dotnet run`. The values are case-sensitive. + +| `commandName` | Behavior | +| --- | --- | +| `Project` | Builds the project and starts the command produced by the project. | +| `Executable` | Starts the command specified by `executablePath`. Unless you specify `--no-build`, `dotnet run` still builds the project first. | + +### Common properties + +`dotnet run` recognizes these properties for both supported profile types: + +`dotnet run` expands `%NAME%` environment-variable references in supported string values. In .NET 11 and later versions, it also expands MSBuild property references in values that it uses to launch the process, using the same token replacement as Visual Studio. It doesn't expand shell-style `$NAME` references. + +| Property | Behavior | +| --- | --- | +| `commandLineArgs` | Specifies arguments for the launched process. Explicit application arguments on the command line take precedence. For a `Project` profile, arguments supplied by the project also take precedence. | +| `environmentVariables` | Specifies environment variables for the launched process. Profile values override inherited and SDK-generated environment variables, and `-e\|--environment` values override profile values. | +| `dotnetRunMessages` | When `true`, prints `Building...` before `dotnet run` builds the project. The default is `false`. This property doesn't control the message that identifies the launch settings file. | + +Use `environmentVariables` to apply development-time runtime configuration settings that have an environment-variable form. For example, a profile can set GC settings such as `DOTNET_gcServer`. For the available settings, environment-variable names, and precedence rules, see [.NET runtime configuration settings](../runtime-config/index.md) and [Runtime configuration options for garbage collection](../runtime-config/garbage-collector.md). + +Not every runtime setting has an environment-variable form. To configure an app independently of its launch profile, use an MSBuild property or `RuntimeHostConfigurationOption` item in the project, or use a `runtimeconfig.template.json` file. Some settings can also be changed in code with . These mechanisms produce or modify the app's runtime configuration; they aren't additional `launchSettings.json` properties. + +### `Project` properties + +`dotnet run` recognizes these additional properties when `commandName` is `Project`: + +| Property | Behavior | +| --- | --- | +| `applicationUrl` | Sets `ASPNETCORE_URLS` in the launched process. An `ASPNETCORE_URLS` value in `environmentVariables` or from `-e\|--environment` takes precedence. | +| `launchBrowser` | Tells launch tooling whether to open a browser. `dotnet run` retains this property in the parsed profile but doesn't open a browser. | +| `launchUrl` | Tells launch tooling which URL to open. `dotnet run` retains this property in the parsed profile but doesn't open a browser or use the URL. | + +The `applicationUrl` behavior supports ASP.NET Core, but launch profiles and the other common properties apply to any runnable SDK-style .NET project. + +### `Executable` properties + +`dotnet run` recognizes these additional properties when `commandName` is `Executable`: + +| Property | Behavior | +| --- | --- | +| `executablePath` | Required. Specifies the process to start. The SDK expands supported variable references, but it doesn't resolve a relative value against the launch settings file. Use an absolute path or a command that the operating system can locate. | +| `workingDirectory` | Optional. Specifies the working directory for the launched process. The SDK expands supported variable references and resolves a relative path against the directory that contains the launch settings file. If you omit the property, the working directory defaults to the directory that contains the project or file-based app. | + +### Visual Studio and debugger extensions + +`launchSettings.json` is a shared input format, but each consumer decides which values to support and how to interpret them. Visual Studio, debuggers, and other tools can recognize more `commandName` values and properties than `dotnet run`. + +The following table compares the `dotnet run` contract with the common .NET project-system behavior in Visual Studio: + +| Setting or behavior | `dotnet run` | Visual Studio | +| --- | --- | --- | +| Supported profile types | Supports `Project` and `Executable`. | Supports `Project`, `Executable`, and an empty `commandName`. Installed project-system extensions can add other profile types. | +| Variable expansion | Expands `%NAME%` environment-variable references. In .NET 11 and later versions, also expands MSBuild property references in values that it uses to launch the process. | Expands environment variables and MSBuild properties in `executablePath`, `commandLineArgs`, `workingDirectory`, `launchUrl`, environment-variable values, and string-valued extension settings. | +| `commandLineArgs` for `Project` | Uses the profile value only when the project doesn't provide run arguments and you don't pass application arguments on the command line. | Appends the profile value to the run arguments from the project. | +| `workingDirectory` for `Project` | Ignores the property. | Supports the property. A relative path is relative to the project directory. | +| `workingDirectory` for `Executable` | A relative path is relative to the directory that contains the launch settings file. If omitted, the path defaults to the project or file-based app directory. | A relative path is relative to the project directory. If omitted, the path defaults to the output directory when that directory exists, or to the project directory otherwise. | +| Relative `executablePath` | Passes the value to the operating system without rebasing it. | Resolves a value with path components from the profile's working directory. For a bare executable name, Visual Studio checks its own current directory and then `PATH`. | +| `launchBrowser` and `launchUrl` | Retains the values in the parsed profile but doesn't open a browser. | Makes the values available to a launch provider. For example, ASP.NET Core tooling can open a browser. | +| `applicationUrl` | Sets `ASPNETCORE_URLS`. | Makes the value available to installed launch providers, such as ASP.NET Core tooling. | +| `dotnetRunMessages` | Controls the `Building...` message. | Doesn't use the property to control Visual Studio output. | +| Debugger properties | Ignores debugger-specific properties. | Uses properties such as `nativeDebugging`, `sqlDebugging`, `jsWebView2Debugging`, `remoteDebugEnabled`, and `hotReloadEnabled` when the project and debugger support the feature. | + +In .NET 11 and later versions, both consumers expand `"$(ProjectDir)"`. In earlier versions, no single `workingDirectory` value identifies the project directory for both consumers. Visual Studio expands `"$(ProjectDir)"`, while `dotnet run` treats it as literal text and resolves relative paths from the directory that contains the launch settings file. Therefore, use `".."` for `dotnet run` with a conventional `Properties/launchSettings.json` or `My Project/launchSettings.json` file. Visual Studio resolves the same value to the parent of the project directory. + +Windows Forms and WPF apps don't add another `dotnet run` profile type. Use a `Project` profile with common settings such as `commandLineArgs` and `environmentVariables`. In Visual Studio, these desktop project types can also use applicable debugger properties, such as `nativeDebugging` for mixed managed and native debugging or `jsWebView2Debugging` for WebView2. Browser and URL properties only have an effect when a launch provider or the application consumes them. + +Other project types and Visual Studio workloads can install launch providers that add profile types or interpret extra properties. Those extensions don't add support to `dotnet run`: the CLI skips unsupported profile types during default selection and reports an error when you select one explicitly. + +For Visual Studio's supported debugger settings and project UI, see [Project settings for a .NET C# debug configuration](/visualstudio/debugger/project-settings-for-csharp-debug-configurations-dotnetcore). + ## Arguments `` @@ -126,7 +233,7 @@ The `--` separator marks every following token as an application argument, so `d - **`-lp|--launch-profile `** - The name of the launch profile (if any) to use when launching the application. Launch profiles are defined in the *launchSettings.json* file and are typically called `Development`, `Staging`, and `Production`. For more information, see [Working with multiple environments](/aspnet/core/fundamentals/environments). + The name of the launch profile to use when launching the application. For more information, see [Launch profiles](#launch-profiles). - **`--no-build`** @@ -189,11 +296,12 @@ The `--` separator marks every following token as an application argument, so `d ## Environment variables -There are four mechanisms by which environment variables can be applied to the launched application: +The following sources apply environment variables to the launched application: 1. Ambient environment variables from the operating system when the command is run. 1. System.CommandLine `env` directives, like `[env:key=value]`. These apply to the entire `dotnet run` process, not just the project being run by `dotnet run`. -1. `environmentVariables` from the chosen launch profile (`-lp`) in the project's [launchSettings.json file](/aspnet/core/fundamentals/environments#lsj), if any. These apply to the project being run by `dotnet run`. +1. Values generated from the chosen launch profile. `dotnet run` sets `DOTNET_LAUNCH_PROFILE`, and `applicationUrl` in a `Project` profile sets `ASPNETCORE_URLS`. +1. `environmentVariables` from the [chosen launch profile](#launch-profiles), if any. These apply to the project being run by `dotnet run`. 1. `-e|--environment` CLI option values (added in .NET SDK version 9.0.200). These apply to the project being run by `dotnet run`. The environment is constructed in the same order as this list, so the `-e|--environment` option has the highest precedence. diff --git a/docs/framework/release-notes/2026/08-11-august-cumulative-update.md b/docs/framework/release-notes/2026/08-11-august-cumulative-update.md index 1f7f25c3b7023..6d234374e6905 100644 --- a/docs/framework/release-notes/2026/08-11-august-cumulative-update.md +++ b/docs/framework/release-notes/2026/08-11-august-cumulative-update.md @@ -1,12 +1,13 @@ --- title: August 2026 cumulative update description: Learn about the improvements in the .NET Framework August 2026 cumulative update. -ms.date: 08/11/2026 +ms.date: 09/02/2026 ai-usage: ai-generated --- # .NET Framework August 2026 cumulative update _Released August 11, 2026_ +_Updated September 2, 2026, to include known issues._ ## Summary of what's new in this release @@ -45,7 +46,51 @@ There are no new quality and reliability improvements in this release. ## Known issues in this release -This release contains no known issues. +#### Known issue + +After installing the August 2026 .NET Framework cumulative update, some Windows Presentation Foundation (WPF) applications might fail with a `System.IO.FileFormatException` when printing or generating PDF/XPS content that uses certain fonts, including Calibri. + +#### Workaround + +Applications can mitigate this issue by enabling the `Switch.MS.Internal.TtfDelta.DisableCmapAndSbitOverflowProtection` AppContext switch in the application configuration file: + +```xml + + + + + +``` + +This switch disables security protections introduced in the August 2026 update and might increase exposure to the vulnerabilities addressed by that update. Microsoft recommends using this workaround only as a temporary measure and only when required to address this issue. + +#### Status + +Investigating. + +#### Known Issue + +After installing the August 2026 .NET Framework cumulative update, WPF applications that print—or display print preview—from an in-memory XPS document registered with `System.IO.Packaging.PackageStore` may fail with a `System.IO.FileFormatException` while the document is loading. This occurs when the package identity used as both the `PackageStore` key and the `XpsDocument` package identity is an absolute URI that uses the `pack` scheme—for example, `pack://.xps`. Images and fonts contained within the same XPS package are then incorrectly rejected as being outside the package. Application code and XPS content do not need to have changed for this failure to occur. + +#### Workaround + +Applications that can be rebuilt should use an absolute package identity that doesn't use the `pack` scheme—for example, `xpspack://.xps`. This resolves the failure while keeping the protections introduced in the August 2026 update enabled. For applications that can't be rebuilt, enable the `Switch.System.Windows.DisableXpsPackageBoundaryRestriction` AppContext switch in the application configuration file: + +```xml + + + + + +``` + +This switch disables security protections introduced in the August 2026 update and might increase exposure to the vulnerabilities addressed by that update. Microsoft recommends using this workaround only as a temporary measure and only when required to address this issue. + +#### Status + +Investigating. ## Summary tables diff --git a/docs/orleans/Directory.Build.props b/docs/orleans/Directory.Build.props index 9a70bee63fffd..8449fed0ee40d 100644 --- a/docs/orleans/Directory.Build.props +++ b/docs/orleans/Directory.Build.props @@ -16,7 +16,7 @@ - + diff --git a/docs/orleans/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj b/docs/orleans/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj index aa531566426db..cfc70bf94d178 100644 --- a/docs/orleans/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj +++ b/docs/orleans/deployment/snippets/service-fabric/stateless/Orleans.ServiceFabric.Stateless.csproj @@ -10,7 +10,7 @@ - + diff --git a/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj b/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj index ca242f7413670..6d9e24aa54dee 100644 --- a/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj +++ b/docs/orleans/grains/snippets/transactions/Abstractions/Abstractions.csproj @@ -1,7 +1,7 @@ - + diff --git a/docs/orleans/grains/snippets/transactions/Client/Client.csproj b/docs/orleans/grains/snippets/transactions/Client/Client.csproj index 5783b79af8690..ca401486ad162 100644 --- a/docs/orleans/grains/snippets/transactions/Client/Client.csproj +++ b/docs/orleans/grains/snippets/transactions/Client/Client.csproj @@ -5,7 +5,7 @@ - + diff --git a/docs/orleans/grains/snippets/transactions/Server/Server.csproj b/docs/orleans/grains/snippets/transactions/Server/Server.csproj index 67d6ba4f8eb68..f8aa615e9ae78 100644 --- a/docs/orleans/grains/snippets/transactions/Server/Server.csproj +++ b/docs/orleans/grains/snippets/transactions/Server/Server.csproj @@ -5,7 +5,7 @@ - + diff --git a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj index bda4c4d93df8c..59cf1cb7bf819 100644 --- a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj +++ b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj @@ -6,7 +6,7 @@ - + diff --git a/docs/orleans/tutorials-and-samples/snippets/minimal/Client/Client.csproj b/docs/orleans/tutorials-and-samples/snippets/minimal/Client/Client.csproj index d6e7f24a0fb9a..2a14a5d76b35a 100644 --- a/docs/orleans/tutorials-and-samples/snippets/minimal/Client/Client.csproj +++ b/docs/orleans/tutorials-and-samples/snippets/minimal/Client/Client.csproj @@ -6,7 +6,7 @@ - + diff --git a/docs/orleans/tutorials-and-samples/snippets/minimal/GrainInterfaces/GrainInterfaces.csproj b/docs/orleans/tutorials-and-samples/snippets/minimal/GrainInterfaces/GrainInterfaces.csproj index d8b601f5ffb2b..c7510473417d6 100644 --- a/docs/orleans/tutorials-and-samples/snippets/minimal/GrainInterfaces/GrainInterfaces.csproj +++ b/docs/orleans/tutorials-and-samples/snippets/minimal/GrainInterfaces/GrainInterfaces.csproj @@ -2,8 +2,8 @@ - - + + diff --git a/docs/orleans/tutorials-and-samples/snippets/minimal/Grains/Grains.csproj b/docs/orleans/tutorials-and-samples/snippets/minimal/Grains/Grains.csproj index 03f3b31c37355..bba060aa2857a 100644 --- a/docs/orleans/tutorials-and-samples/snippets/minimal/Grains/Grains.csproj +++ b/docs/orleans/tutorials-and-samples/snippets/minimal/Grains/Grains.csproj @@ -2,7 +2,7 @@ - + diff --git a/docs/orleans/tutorials-and-samples/snippets/minimal/Silo/Silo.csproj b/docs/orleans/tutorials-and-samples/snippets/minimal/Silo/Silo.csproj index d0940274c4d24..aa57a9b8c2959 100644 --- a/docs/orleans/tutorials-and-samples/snippets/minimal/Silo/Silo.csproj +++ b/docs/orleans/tutorials-and-samples/snippets/minimal/Silo/Silo.csproj @@ -6,8 +6,8 @@ - - + +