diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 83eefc4b78513..2c27ebfb1cd3b 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -482,6 +482,12 @@ updates: interval: "weekly" day: "wednesday" open-pull-requests-limit: 5 + - package-ecosystem: "nuget" + directory: "/docs/csharp/asynchronous-programming/snippets/async-scenarios" #async-scenarios.csproj + schedule: + interval: "weekly" + day: "wednesday" + open-pull-requests-limit: 5 - package-ecosystem: "nuget" directory: "/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/finished" #IssuePRreport.csproj schedule: @@ -1197,7 +1203,7 @@ updates: day: "wednesday" open-pull-requests-limit: 5 - package-ecosystem: "nuget" - directory: "/samples/snippets/visualbasic/VS_Snippets_ADO.NET/DP Custom CopyToDataTable Examples/VB" #CustomCopyToDataTableVB.vbproj + directory: "/samples/snippets/visualbasic/VS_Snippets_ADO.NET/DP LINQ to DataSet Examples/VB" #LINQtoDataSetExamplesVB.vbproj schedule: interval: "weekly" day: "wednesday" diff --git a/docs/architecture/serverless/serverless-business-scenarios.md b/docs/architecture/serverless/serverless-business-scenarios.md index 32a6798669acb..8aa396a3d330b 100644 --- a/docs/architecture/serverless/serverless-business-scenarios.md +++ b/docs/architecture/serverless/serverless-business-scenarios.md @@ -79,7 +79,7 @@ A reference architecture that walks you through the decision-making process invo ## Serverless for mobile -Azure Functions are easy to implement and maintain, and accessible through HTTP. They are a great way to implement an API for a mobile application. Microsoft offers great cross-platform tools for iOS, Android, and Windows with Xamarin. As such, Xamarin and Azure Functions are working great together. This article shows how to implement an Azure Function in the Azure portal or in Visual Studio at first, and build a cross-platform client with Xamarin.Forms running on Android, iOS, and Windows. +Azure Functions are easy to implement and maintain, and accessible through HTTP. They're a good way to implement an API for a mobile application. Microsoft offers cross-platform tools for iOS, Android, and Windows with Xamarin. As such, Xamarin and Azure Functions work well together. This article shows how to implement an Azure Function in the Azure portal or in Visual Studio, and then build a cross-platform client with Xamarin.Forms running on Android, iOS, and Windows. [Implementing a simple Azure Function with a Xamarin.Forms client](/samples/azure-samples/functions-xamarin-getting-started/implementing-a-simple-azure-function-with-a-xamarinforms-client/) diff --git a/docs/azure/configure-visual-studio.md b/docs/azure/configure-visual-studio.md index 2ee0d36252636..f14392fce0a7e 100644 --- a/docs/azure/configure-visual-studio.md +++ b/docs/azure/configure-visual-studio.md @@ -9,7 +9,7 @@ ms.author: alexwolf --- # Configure Visual Studio for Azure development with .NET -Visual Studio includes tooling to help with the development and deployment of applications on Azure. This guide will help you make sure that Visual Studio is properly configured for Azure development. +Visual Studio includes tooling to help with the development and deployment of applications on Azure. This guide helps you make sure that Visual Studio is properly configured for Azure development. ## Download Visual Studio @@ -20,13 +20,13 @@ If you already have Visual Studio installed, you can skip this step. ## Install Azure workloads -Open Visual Studio Installer and validate that the workloads **Azure development** and **ASP.NET and web development** are installed. If either of these workloads is not installed, select them to be installed. +Open Visual Studio Installer and validate that the workloads **Azure development** and **ASP.NET and web development** are installed. If either of these workloads isn't installed, select them to be installed. ![Screenshot of the Visual Studio Installer showing the Azure development and ASP.NET and Web Development Workloads selected](./media/visual-studio-installer-azure-development.png) ## Authenticate Visual Studio with Azure -When debugging apps through Visual Studio, Visual Studio can use your Azure account to authenticate and access Azure Resources. This account is also used when you publish apps directly from Visual Studio to Azure. +When you debug apps through Visual Studio, Visual Studio can use your Azure account to authenticate and access Azure Resources. This account is also used when you publish apps directly from Visual Studio to Azure. To authenticate your Azure account from Visual Studio, select the **Tools** > **Options** menu to launch the **Options** dialog. Navigate to the **Azure Service Authentication** options and sign in using your Azure account. diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index df2b85b4c08a7..e1932d5a5f208 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -69,12 +69,12 @@ | Schema Registry | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.3.0)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.3.0/sdk/schemaregistry/Azure.Data.SchemaRegistry/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.4.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | | Schema Registry - Avro | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/1.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.0/sdk/schemaregistry/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/) | | Service Bus | NuGet [7.16.2](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.16.2) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.16.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.16.2/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Storage - Blobs | NuGet [12.18.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.18.0) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.18.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.18.0/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs Batch | NuGet [12.15.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.15.0) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.15.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.15.0/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.38](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.38) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.38](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.38/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Files Data Lake | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.16.0) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.16.0/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Share | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.16.0) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.16.0/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Queues | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.16.0) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.16.0/sdk/storage/Azure.Storage.Queues/) | +| Storage - Blobs | NuGet [12.18.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.18.0)
NuGet [12.19.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.19.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.18.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.18.0/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.19.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.19.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs Batch | NuGet [12.15.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.15.0)
NuGet [12.16.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.16.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.15.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.15.0/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.16.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.16.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.39](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.39) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.39](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.39/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Files Data Lake | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.16.0)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.16.0/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.17.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Share | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.16.0)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.16.0/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.17.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Queues | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.16.0)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.16.0/sdk/storage/Azure.Storage.Queues/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.17.0-beta.1/sdk/storage/Azure.Storage.Queues/) | | Synapse - AccessControl | NuGet [1.0.0-preview.5](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.5) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.5/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | | Synapse - Artifacts | NuGet [1.0.0-preview.18](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.18) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.18](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.18/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | | Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.5/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | @@ -95,7 +95,7 @@ | Functions extension for Azure Tables | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Tables/1.2.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Tables-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Tables_1.2.0/sdk/tables/Microsoft.Azure.WebJobs.Extensions.Tables/) | | Key Encryptor for .NET Data Protection | NuGet [1.2.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.2.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.2.2/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | | Secrets Configuration Provider for .NET | NuGet [1.2.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.2.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.2.2/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| Storage - Common | NuGet [12.17.0](https://www.nuget.org/packages/Azure.Storage.Common/12.17.0) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.17.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.17.0/sdk/storage/Azure.Storage.Common/) | +| Storage - Common | NuGet [12.17.0](https://www.nuget.org/packages/Azure.Storage.Common/12.17.0)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.17.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.17.0/sdk/storage/Azure.Storage.Common/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.18.0-beta.1/sdk/storage/Azure.Storage.Common/) | | WebJobs Extensions - Event Grid | NuGet [3.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventGrid-readme) | GitHub [3.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventGrid_3.3.0/sdk/eventgrid/Microsoft.Azure.WebJobs.Extensions.EventGrid/) | | WebJobs Extensions - Event Hubs | NuGet [6.0.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/6.0.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventHubs-readme) | GitHub [6.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventHubs_6.0.1/sdk/eventhub/Microsoft.Azure.WebJobs.Extensions.EventHubs/) | | WebJobs Extensions - Service Bus | NuGet [5.13.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.13.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.ServiceBus-readme) | GitHub [5.13.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.13.0/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index c260b2c3dab5d..9422748d33d9b 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -70,12 +70,12 @@ | Schema Registry | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.3.0)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.Data.SchemaRegistry/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/Data.SchemaRegistry-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.3.0/sdk/schemaregistry/Azure.Data.SchemaRegistry/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.SchemaRegistry_1.4.0-beta.2/sdk/schemaregistry/Azure.Data.SchemaRegistry/) | | Schema Registry - Avro | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/1.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.0/sdk/schemaregistry/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/) | | Service Bus | NuGet [7.16.2](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.16.2) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.16.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.16.2/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Storage - Blobs | NuGet [12.18.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.18.0) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.18.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.18.0/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs Batch | NuGet [12.15.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.15.0) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.15.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.15.0/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.38](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.38) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.38](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.38/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Files Data Lake | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.16.0) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.16.0/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Share | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.16.0) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.16.0/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Queues | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.16.0) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.16.0/sdk/storage/Azure.Storage.Queues/) | +| Storage - Blobs | NuGet [12.18.0](https://www.nuget.org/packages/Azure.Storage.Blobs/12.18.0)
NuGet [12.19.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.19.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.18.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.18.0/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.19.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.19.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs Batch | NuGet [12.15.0](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.15.0)
NuGet [12.16.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.16.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.15.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.15.0/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.16.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.16.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.39](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.39) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.39](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.39/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Files Data Lake | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.16.0)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.16.0/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.17.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Share | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.16.0)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.16.0/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.17.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Queues | NuGet [12.16.0](https://www.nuget.org/packages/Azure.Storage.Queues/12.16.0)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.16.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.16.0/sdk/storage/Azure.Storage.Queues/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.17.0-beta.1/sdk/storage/Azure.Storage.Queues/) | | Synapse - AccessControl | NuGet [1.0.0-preview.5](https://www.nuget.org/packages/Azure.Analytics.Synapse.AccessControl/1.0.0-preview.5) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.AccessControl-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.AccessControl_1.0.0-preview.5/sdk/synapse/Azure.Analytics.Synapse.AccessControl/) | | Synapse - Artifacts | NuGet [1.0.0-preview.18](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.18) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.18](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.18/sdk/synapse/Azure.Analytics.Synapse.Artifacts/) | | Synapse - Managed Private Endpoints | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.Analytics.Synapse.ManagedPrivateEndpoints/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.ManagedPrivateEndpoints-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.ManagedPrivateEndpoints_1.0.0-beta.5/sdk/synapse/Azure.Analytics.Synapse.ManagedPrivateEndpoints/) | @@ -96,7 +96,7 @@ | Functions extension for Azure Tables | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Tables/1.2.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Tables-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Tables_1.2.0/sdk/tables/Microsoft.Azure.WebJobs.Extensions.Tables/) | | Key Encryptor for .NET Data Protection | NuGet [1.2.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.2.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.2.2/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | | Secrets Configuration Provider for .NET | NuGet [1.2.2](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.2.2) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.2.2/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| Storage - Common | NuGet [12.17.0](https://www.nuget.org/packages/Azure.Storage.Common/12.17.0) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.17.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.17.0/sdk/storage/Azure.Storage.Common/) | +| Storage - Common | NuGet [12.17.0](https://www.nuget.org/packages/Azure.Storage.Common/12.17.0)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.17.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.17.0/sdk/storage/Azure.Storage.Common/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.18.0-beta.1/sdk/storage/Azure.Storage.Common/) | | WebJobs Extensions - Event Grid | NuGet [3.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventGrid-readme) | GitHub [3.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventGrid_3.3.0/sdk/eventgrid/Microsoft.Azure.WebJobs.Extensions.EventGrid/) | | WebJobs Extensions - Event Hubs | NuGet [6.0.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/6.0.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventHubs-readme) | GitHub [6.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventHubs_6.0.1/sdk/eventhub/Microsoft.Azure.WebJobs.Extensions.EventHubs/) | | WebJobs Extensions - Service Bus | NuGet [5.13.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.13.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.ServiceBus-readme) | GitHub [5.13.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.13.0/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/) | diff --git a/docs/azure/sdk/unit-testing-mocking.md b/docs/azure/sdk/unit-testing-mocking.md index a1f6da6dbfa3e..b128c1214274d 100644 --- a/docs/azure/sdk/unit-testing-mocking.md +++ b/docs/azure/sdk/unit-testing-mocking.md @@ -9,7 +9,7 @@ ms.date: 07/05/2023 Unit testing is an important part of a sustainable development process that can improve code quality and prevent regressions or bugs in your apps. However, unit testing presents challenges when the code you're testing performs network calls, such as those made to Azure resources. Tests that run against live services can experience issues, such as latency that slows down test execution, dependencies on code outside of the isolated test, and issues with managing service state and costs every time the test is run. Instead of testing against live Azure services, replace the service clients with mocked or in-memory implementations. This avoids the above issues and lets developers focus on testing their application logic, independent from the network and service. -In this article, you'll learn how to write unit tests for the Azure SDK for .NET that isolate your dependencies to make your tests more reliable. You'll also learn how to replace key components with in-memory test implementations to create fast and reliable unit tests, and see how to design your own classes to better support unit testing. This article includes examples that use [Moq](https://www.nuget.org/packages/moq/) and [NSubstitute](https://www.nuget.org/packages/nsubstitute/), which are popular mocking libraries for .NET. +In this article, you learn how to write unit tests for the Azure SDK for .NET that isolate your dependencies to make your tests more reliable. You also learn how to replace key components with in-memory test implementations to create fast and reliable unit tests, and see how to design your own classes to better support unit testing. This article includes examples that use [Moq](https://www.nuget.org/packages/moq/) and [NSubstitute](https://www.nuget.org/packages/nsubstitute/), which are popular mocking libraries for .NET. ## Understand service clients @@ -181,7 +181,7 @@ When unit testing you only want the unit tests to verify the application logic a ## Refactor your types for testability -Classes that need to be tested should be designed for [dependency injection](dependency-injection.md), which allows the class to receive its dependencies instead of creating them internally. It was a seamless process to replace the `SecretClient` implementation in the example from the previous section because it was one of the constructor parameters. However, there may be classes in your code that create their own dependencies and aren't easily testable, such as the following: +Classes that need to be tested should be designed for [dependency injection](dependency-injection.md), which allows the class to receive its dependencies instead of creating them internally. It was a seamless process to replace the `SecretClient` implementation in the example from the previous section because it was one of the constructor parameters. However, there might be classes in your code that create their own dependencies and aren't easily testable, such as the following class: ```csharp public class AboutToExpireSecretFinder diff --git a/docs/core/compatibility/sdk/8.0/custombuildeventargs.md b/docs/core/compatibility/sdk/8.0/custombuildeventargs.md index f67246cfdaddb..f57f1a89ba7b2 100644 --- a/docs/core/compatibility/sdk/8.0/custombuildeventargs.md +++ b/docs/core/compatibility/sdk/8.0/custombuildeventargs.md @@ -17,7 +17,7 @@ Starting in .NET 8, a build error is issued if your code uses any type derived f > Usage of unsecure BinaryFormatter during serialization of custom event type 'MyCustomBuildEventArgs'. This will be deprecated soon. Please use Extended*EventArgs instead. More info: -If you build from Visual Studio, there is no change in behavior unless you opt in by setting the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable to 1 (available in Visual Studio version 17.8 and later). +If you build from Visual Studio, there's no change in behavior unless you opt in by setting the `MSBUILDCUSTOMBUILDEVENTWARNING` environment variable to 1 (available in Visual Studio version 17.8 and later). ## Version introduced @@ -40,7 +40,7 @@ Use one of the following newly introduced, built-in events for extensibility ins - `Microsoft.Build.Framework.ExtendedBuildMessageEventArgs` - `Microsoft.Build.Framework.ExtendedBuildWarningEventArgs` -Alternatively, you can temporarily disable the check by explicitly setting the environment variable `MSBUILDCUSTOMBUILDEVENTWARNING` to something other than 1. +Alternatively, you can temporarily disable the check by explicitly setting the environment variable `MSBUILDCUSTOMBUILDEVENTWARNING` to something other than `1`. ## Affected APIs diff --git a/docs/core/deploying/native-aot/diagnostics.md b/docs/core/deploying/native-aot/diagnostics.md index d0bb6ff56adf0..26dbb05e9ac41 100644 --- a/docs/core/deploying/native-aot/diagnostics.md +++ b/docs/core/deploying/native-aot/diagnostics.md @@ -8,7 +8,7 @@ ms.date: 08/07/2023 # Diagnostics and instrumentation -Native AOT shares some, but not all, diagnostics and instrumentation capabilities with CoreCLR. Because of CoreCLR's rich selection of diagnostic utilities, it's sometimes appropriate to diagnose and debug problems in CoreCLR. Apps that are [trim-compatible](../trimming/prepare-libraries-for-trimming.md) should not have behavioral differences, so investigations often apply to both runtimes. Nonetheless, some information can only be gathered after publishing, so Native AOT also provides post-publish diagnostic tooling. +Native AOT shares some, but not all, diagnostics and instrumentation capabilities with CoreCLR. Because of CoreCLR's rich selection of diagnostic utilities, it's sometimes appropriate to diagnose and debug problems in CoreCLR. Apps that are [trim-compatible](../trimming/prepare-libraries-for-trimming.md) shouldn't have behavioral differences, so investigations often apply to both runtimes. Nonetheless, some information can only be gathered after publishing, so Native AOT also provides post-publish diagnostic tooling. ## .NET 8 Native AOT diagnostic support @@ -39,17 +39,16 @@ Native AOT provides partial support for some [well-known event providers](../../ The .NET CLI tooling (`dotnet` SDK) and Visual Studio offer separate commands for `build` and `publish`. `build` (or `Start` in Visual Studio) uses CoreCLR. Only `publish` creates a Native AOT application. Publishing your app as Native AOT produces an app that has been -ahead-of-time (AOT) compiled to native code. As mentioned previously, this means that not all diagnostic -tools will work seamlessly with published Native AOT applications in .NET 8. However, all .NET +ahead-of-time (AOT) compiled to native code. As mentioned previously, not all diagnostic +tools work seamlessly with published Native AOT applications in .NET 8. However, all .NET diagnostic tools are available for developers during the application building stage. We recommend -developing, debugging, and testing the applications as usual and publishing the working app with Native -AOT as one of the last steps. +developing, debugging, and testing the applications as usual and publishing the working app with Native AOT as one of the last steps. ## Native debugging -When you run your app during development, like inside Visual Studio, or with `dotnet run`, `dotnet build`, or `dotnet test`, it runs on CoreCLR by default. However, if `PublishAot` is present in the project file, the behavior should be the same between CoreCLR and Native AOT. This allows you to use the standard Visual Studio managed debugging engine for development and testing. +When you run your app during development, like inside Visual Studio, or with `dotnet run`, `dotnet build`, or `dotnet test`, it runs on CoreCLR by default. However, if `PublishAot` is present in the project file, the behavior should be the same between CoreCLR and Native AOT. This characteristic allows you to use the standard Visual Studio managed debugging engine for development and testing. -After publishing, Native AOT applications are true native binaries. The managed debugger will not work on them. However, the Native AOT compiler generates fully native executable files that can be debugged by native debuggers on your platform of choice (for example, WinDbg or Visual Studio on Windows and gdb or lldb on Unix-like systems). +After publishing, Native AOT applications are true native binaries. The managed debugger won't work on them. However, the Native AOT compiler generates fully native executable files that native debuggers can debug on your platform of choice (for example, WinDbg or Visual Studio on Windows and gdb or lldb on Unix-like systems). The Native AOT compiler generates information about line numbers, types, locals, and parameters. The native debugger lets you inspect stack trace and variables, step into or over source lines, or set line breakpoints. @@ -60,7 +59,7 @@ Collecting a [dump](../../diagnostics/dumps.md) file for a Native AOT applicatio ### Visual Studio-specific notes -You can launch a Native AOT-compiled executable under the Visual Studio debugger by opening it in the Visual Studio IDE. You will need to [open the executable itself in Visual Studio](/visualstudio/debugger/how-to-debug-an-executable-not-part-of-a-visual-studio-solution). +You can launch a Native AOT-compiled executable under the Visual Studio debugger by opening it in the Visual Studio IDE. You need to [open the executable itself in Visual Studio](/visualstudio/debugger/how-to-debug-an-executable-not-part-of-a-visual-studio-solution). To set a breakpoint that breaks whenever an exception is thrown, choose the **Breakpoints** option from the **Debug > Windows** menu. In the new window, select **New > Function** breakpoint. Specify `RhThrowEx` as the Function Name and leave the Language option at **All Languages** (don't select C#). @@ -68,7 +67,7 @@ To see what exception was thrown, start debugging (**Debug > Start Debugging** o ### Importance of the symbol file -When publishing, the Native AOT compiler produces both an executable and a symbol file. Native debugging, and related activities like profiling, require access to the native symbol file. If this file is not present, you may have degraded or broken results. +When publishing, the Native AOT compiler produces both an executable and a symbol file. Native debugging, and related activities like profiling, require access to the native symbol file. If this file isn't present, you might have degraded or broken results. For information about the name and location of the symbol file, see [Native debug information](index.md#native-aot-deployment). @@ -78,4 +77,4 @@ Platform-specific tools like [PerfView](https://github.com/microsoft/perfview) a ## Heap analysis -Managed heap analysis is not currently supported in Native AOT. Heap analysis tools like [dotnet-gcdump](../../diagnostics/dotnet-gcdump.md), [PerfView](https://github.com/microsoft/perfview), and Visual Studio heap analysis tools don't work in Native AOT in .NET 8. +Managed heap analysis isn't currently supported in Native AOT. Heap analysis tools like [dotnet-gcdump](../../diagnostics/dotnet-gcdump.md), [PerfView](https://github.com/microsoft/perfview), and Visual Studio heap analysis tools don't work in Native AOT in .NET 8. diff --git a/docs/core/deploying/native-aot/warnings/il3050.md b/docs/core/deploying/native-aot/warnings/il3050.md index 62ec4ef3c17d6..b982ace3bb53d 100644 --- a/docs/core/deploying/native-aot/warnings/il3050.md +++ b/docs/core/deploying/native-aot/warnings/il3050.md @@ -11,11 +11,11 @@ f1_keywords: ## Cause -When publishing an app as Native AOT (by setting the `PublishAot` property in a project to `true`), calling members annotated with the `RequiresDynamicCodeAttribute` attribute may result in exceptions at run time. Members annotated with this attribute may require ability to dynamically create new code at run time, and Native AOT publishing model doesn't provide a way to generate native code at run time. +When you publish an app as Native AOT (by setting the `PublishAot` property to `true` in a project), calling members annotated with the `RequiresDynamicCodeAttribute` attribute might result in exceptions at run time. Members annotated with this attribute might require ability to dynamically create new code at run time, and Native AOT publishing model doesn't provide a way to generate native code at run time. ## Rule description - indicates that the member references code that may require code generation at runtime. + indicates that the member references code that might require code generation at run time. ## Example diff --git a/docs/core/deploying/native-aot/warnings/il3055.md b/docs/core/deploying/native-aot/warnings/il3055.md index acb7e2e7cc767..43437c16d1eb7 100644 --- a/docs/core/deploying/native-aot/warnings/il3055.md +++ b/docs/core/deploying/native-aot/warnings/il3055.md @@ -19,7 +19,7 @@ Marshalling code is generated for delegate types that either: - Appear as fields of types passed to native code via P/Invoke. - Are decorated with . -If a concrete type cannot be inferred from the P/Invoke signature, marshalling code might not be available at run time and the P/Invoke will throw an exception. +If a concrete type can't be inferred from the P/Invoke signature, marshalling code might not be available at run time and the P/Invoke will throw an exception. Replace or in the P/Invoke signature with a concrete delegate type. diff --git a/docs/core/deploying/single-file/warnings/il3000.md b/docs/core/deploying/single-file/warnings/il3000.md index bace00ff5475d..2cd88db4edd3a 100644 --- a/docs/core/deploying/single-file/warnings/il3000.md +++ b/docs/core/deploying/single-file/warnings/il3000.md @@ -13,12 +13,12 @@ f1_keywords: | | Value | |-------------------------------------|--------------------------------------| | **Rule ID** | IL3000 | -| **Category** | [SingleFile](overview.md) | -| **Fix is breaking or non-breaking** | Non-breaking | +| **Category** | [SingleFile](overview.md) | +| **Fix is breaking or nonbreaking** | Nonbreaking | ## Cause -When publishing as a single-file (for example, by setting the PublishSingleFile property in a project to true), calling the `Assembly.Location` property for +When you publish an app as a single file (for example, by setting the `PublishSingleFile` property to `true` in a project), calling the `Assembly.Location` property for assemblies embedded inside the single-file bundle always returns an empty string. ## How to fix violations @@ -28,4 +28,4 @@ removing the call entirely. ## When to suppress warnings -It's appropriate to silence this warning if the assembly being accessed is definitely not in the single-file bundle. This may be the case if the assembly is being loaded dynamically from a file path. +It's appropriate to silence this warning if the assembly being accessed is definitely not in the single-file bundle. The assembly might not be in the bundle if the assembly is loaded dynamically from a file path. diff --git a/docs/core/deploying/single-file/warnings/il3001.md b/docs/core/deploying/single-file/warnings/il3001.md index ce443c3141dfe..52486fbd5739a 100644 --- a/docs/core/deploying/single-file/warnings/il3001.md +++ b/docs/core/deploying/single-file/warnings/il3001.md @@ -13,13 +13,13 @@ f1_keywords: | | Value | |-------------------------------------|--------------------------------------| | **Rule ID** | IL3001 | -| **Category** | [SingleFile](overview.md) | -| **Fix is breaking or non-breaking** | Non-breaking | +| **Category** | [SingleFile](overview.md) | +| **Fix is breaking or nonbreaking** | Nonbreaking | ## Cause -When publishing as a single file (for example, by setting the PublishSingleFile property in a project to true), calling the `Assembly.GetFile(s)` methods for -assemblies embedded inside the single-file bundle always throws an exception, as these methods are not single-file compatible. +When you publish an app as a single file (for example, by setting the `PublishSingleFile` property to `true` in a project), calling the `Assembly.GetFile(s)` methods for +assemblies embedded inside the single-file bundle always throws an exception, as these methods aren't single-file compatible. ## How to fix violations @@ -27,4 +27,4 @@ To embed files in assemblies in single-file bundles, consider using embedded res ## When to suppress warnings -It's appropriate to silence this warning if the assembly being accessed is definitely not in the single-file bundle. This may be the case if the assembly is being loaded dynamically from a file path. +It's appropriate to silence this warning if the assembly being accessed is definitely not in the single-file bundle. The assembly might not be in the bundle if the assembly is loaded dynamically from a file path. diff --git a/docs/core/deploying/single-file/warnings/il3002.md b/docs/core/deploying/single-file/warnings/il3002.md index a764bd7a31346..0558c944434cb 100644 --- a/docs/core/deploying/single-file/warnings/il3002.md +++ b/docs/core/deploying/single-file/warnings/il3002.md @@ -12,12 +12,12 @@ f1_keywords: | | Value | |-------------------------------------|--------------------------------------| | **Rule ID** | IL3002 | -| **Category** | [SingleFile](overview.md) | -| **Fix is breaking or non-breaking** | Non-breaking | +| **Category** | [SingleFile](overview.md) | +| **Fix is breaking or nonbreaking** | Nonbreaking | ## Cause -When publishing an app as a single file (for example, by setting the `PublishSingleFile` property in a project to `true`), calling members annotated with the `RequiresAssemblyFilesAttribute` attribute is not single-file compatible. These calls are not compatible because members annotated with this attribute require assembly files to be on disk, and the assemblies embedded in a single-file app are memory loaded. +When you publish an app as a single file (for example, by setting the `PublishSingleFile` property to `true` in a project), calling members annotated with the `RequiresAssemblyFilesAttribute` attribute is not single-file compatible. These calls aren't compatible because members annotated with this attribute require assembly files to be on disk, and the assemblies embedded in a single-file app are memory loaded. Example: diff --git a/docs/core/deploying/single-file/warnings/il3003.md b/docs/core/deploying/single-file/warnings/il3003.md index 9e9a4cd3894a3..3dfedd4e7dacd 100644 --- a/docs/core/deploying/single-file/warnings/il3003.md +++ b/docs/core/deploying/single-file/warnings/il3003.md @@ -7,77 +7,77 @@ f1_keywords: - "IL3003" - "RequiresAssemblyFiles" --- -# IL3003: 'RequiresAssemblyFilesAttribute' annotations must match across all interface implementations or overrides. +# IL3003: 'RequiresAssemblyFilesAttribute' annotations must match across all interface implementations or overrides | | Value | |-------------------------------------|--------------------------------------| | **Rule ID** | IL3003 | -| **Category** | [SingleFile](overview.md) | -| **Fix is breaking or non-breaking** | Non-breaking | +| **Category** | [SingleFile](overview.md) | +| **Fix is breaking or nonbreaking** | Nonbreaking | ## Cause -When publishing as a single file (for example, by setting the `PublishSingleFile` property in a project to `true`), interface implementations or derived classes with members that don't have matching annotations of `[RequiresAssemblyFiles]` can lead to calling a member with the attribute, which is not single-file compatible. There are four possible scenarios where the warning can be generated: +When you publish an app as a single file (for example, by setting the `PublishSingleFile` property to `true` in a project), interface implementations or derived classes with members that don't have matching annotations of `[RequiresAssemblyFiles]` can lead to calling a member with the attribute, which is not single-file compatible. There are four possible scenarios where the warning can be generated: -A member of a base class has the attribute but the overriding member of the derived class does not have the attribute: +- A member of a base class has the attribute but the overriding member of the derived class doesn't have the attribute: -```csharp -public class Base -{ - [RequiresAssemblyFiles] - public virtual void TestMethod() {} -} -public class Derived : Base -{ - // IL3003: Base member 'Base.TestMethod' with 'RequiresAssemblyFilesAttribute' has a derived member 'Derived.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. - public override void TestMethod() {} -} -``` + ```csharp + public class Base + { + [RequiresAssemblyFiles] + public virtual void TestMethod() {} + } + public class Derived : Base + { + // IL3003: Base member 'Base.TestMethod' with 'RequiresAssemblyFilesAttribute' has a derived member 'Derived.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. + public override void TestMethod() {} + } + ``` -A member of a base class does not have the attribute but the overriding member of the derived class does have the attribute: +- A member of a base class doesn't have the attribute but the overriding member of the derived class does have the attribute: -```csharp -public class Base -{ - public virtual void TestMethod() {} -} -public class Derived : Base -{ - // IL3003: Member 'Derived.TestMethod()' with 'RequiresAssemblyFilesAttribute' overrides base member 'Base.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. - [RequiresAssemblyFiles] - public override void TestMethod() {} -} -``` + ```csharp + public class Base + { + public virtual void TestMethod() {} + } + public class Derived : Base + { + // IL3003: Member 'Derived.TestMethod()' with 'RequiresAssemblyFilesAttribute' overrides base member 'Base.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. + [RequiresAssemblyFiles] + public override void TestMethod() {} + } + ``` -An interface member has the attribute but its implementation does not have the attribute: +- An interface member has the attribute but its implementation doesn't have the attribute: -```csharp -interface IRAF -{ - [RequiresAssemblyFiles] - void TestMethod(); -} -class Implementation : IRAF -{ - // IL3003: Interface member 'IRAF.TestMethod()' with 'RequiresAssemblyFilesAttribute' has an implementation member 'Implementation.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. - public void TestMethod () { } -} -``` + ```csharp + interface IRAF + { + [RequiresAssemblyFiles] + void TestMethod(); + } + class Implementation : IRAF + { + // IL3003: Interface member 'IRAF.TestMethod()' with 'RequiresAssemblyFilesAttribute' has an implementation member 'Implementation.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. + public void TestMethod () { } + } + ``` -An interface member does not have the attribute but its implementation does have the attribute: +- An interface member doesn't have the attribute but its implementation does have the attribute: -```csharp -interface INoRAF -{ - void TestMethod(); -} -class Implementation : INoRAF -{ - [RequiresAssemblyFiles] - // IL3003: Member 'Implementation.TestMethod()' with 'RequiresAssemblyFilesAttribute' implements interface member 'INoRAF.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. - public void TestMethod () { } -} -``` + ```csharp + interface INoRAF + { + void TestMethod(); + } + class Implementation : INoRAF + { + [RequiresAssemblyFiles] + // IL3003: Member 'Implementation.TestMethod()' with 'RequiresAssemblyFilesAttribute' implements interface member 'INoRAF.TestMethod()' without 'RequiresAssemblyFilesAttribute'. For all interfaces and overrides the implementation attribute must match the definition attribute. + public void TestMethod () { } + } + ``` ## How to fix violations @@ -85,4 +85,4 @@ For all interfaces and overrides, the implementation must match the definition i ## When to suppress warnings -This warning should not be suppressed. +You should not suppress this warning. diff --git a/docs/core/deploying/trimming/incompatibilities.md b/docs/core/deploying/trimming/incompatibilities.md index d8f61fea85ec2..e065d2925400c 100644 --- a/docs/core/deploying/trimming/incompatibilities.md +++ b/docs/core/deploying/trimming/incompatibilities.md @@ -7,13 +7,13 @@ ms.date: 10/08/2021 --- # Known trimming incompatibilities -There are some patterns that are known to be incompatible with trimming. Some of these patterns may become compatible as tooling improves or as libraries make modifications to become trimming compatible. +There are some patterns that are known to be incompatible with trimming. Some of these patterns might become compatible as tooling improves or as libraries make modifications to become trimming compatible. ## Built-in COM marshalling Alternative: [COM Wrappers](../../../standard/native-interop/com-wrappers.md) -Automatic [COM marshalling](../../../standard/native-interop/cominterop.md) has been built in to .NET since .NET Framework 1.0. It uses run-time code analysis to automatically convert between native COM objects and managed .NET objects. Unfortunately, trimming analysis cannot always predict what .NET code will need to be preserved for automatic COM marshalling. However, if [COM Wrappers](../../../standard/native-interop/com-wrappers.md) are used instead, trimming analysis can guarantee that all used code will be correctly preserved. +Automatic [COM marshalling](../../../standard/native-interop/cominterop.md) has been built in to .NET since .NET Framework 1.0. It uses run-time code analysis to automatically convert between native COM objects and managed .NET objects. Unfortunately, trimming analysis can't always predict what .NET code needs to be preserved for automatic COM marshalling. However, if [COM Wrappers](../../../standard/native-interop/com-wrappers.md) are used instead, trimming analysis can guarantee that all used code will be correctly preserved. ## WPF @@ -27,7 +27,7 @@ The Windows Forms framework makes minimal use of reflection, but is heavily reli Alternative: Reflection-free serializers. -Many uses of reflection can be made trimming-compatible, as described in [Introduction to trim warnings](fixing-warnings.md). However, serializers tend to have very complex uses of reflection. Many of these uses cannot be made analyzable at build time. Unfortunately, the best option is often to rewrite the system to use source generation instead. +Many uses of reflection can be made trimming-compatible, as described in [Introduction to trim warnings](fixing-warnings.md). However, serializers tend to have complex uses of reflection. Many of these uses can't be made analyzable at build time. Unfortunately, the best option is often to rewrite the system to use source generation instead. Popular reflection-based serializers and their recommended alternatives: @@ -37,4 +37,4 @@ Popular reflection-based serializers and their recommended alternatives: ## Dynamic assembly loading and execution -Trimming and dynamic assembly loading is a common problem for systems that support plugins or extensions, usually through APIs like . Trimming relies on seeing all assemblies at build time, so it knows which code is used and cannot be trimmed away. Most plugin systems load third-party code dynamically, so it's not possible for the trimmer to identify what code is needed. +Trimming and dynamic assembly loading is a common problem for systems that support plugins or extensions, usually through APIs like . Trimming relies on seeing all assemblies at build time, so it knows which code is used and can't be trimmed away. Most plugin systems load third-party code dynamically, so it's not possible for the trimmer to identify what code is needed. diff --git a/docs/core/diagnostics/available-counters.md b/docs/core/diagnostics/available-counters.md index 89a4282d69b79..c6c0bced7b7e2 100644 --- a/docs/core/diagnostics/available-counters.md +++ b/docs/core/diagnostics/available-counters.md @@ -8,6 +8,7 @@ ms.date: 12/17/2020 # Well-known EventCounters in .NET The .NET runtime and libraries implement and publish several [EventCounters](./event-counters.md) that can be used to identify and diagnose various performance issues. This article is a reference on the providers that can be used to monitor these counters and their descriptions. +See the [well-known metrics reference](built-in-metrics.md) instead if you are working with .NET's newer [System.Diagnostics.Metrics API](metrics.md). ## System.Runtime counters diff --git a/docs/core/diagnostics/built-in-metrics-aspnetcore.md b/docs/core/diagnostics/built-in-metrics-aspnetcore.md new file mode 100644 index 0000000000000..e0890cabe8118 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -0,0 +1,401 @@ +--- +title: ASP.NET Core Metrics +description: Review the metrics available for ASP.NET Core +ms.topic: reference +ms.date: 10/16/2023 +--- + +# ASP.NET Core Metrics + +This article describes the metrics built-in for ASP.NET Core produced using the + API. For a listing of metrics based on the older [EventCounters](event-counters.md) API, +see [here](available-counters.md). + +- [Meter: `Microsoft.AspNetCore.Hosting`](#meter-microsoftaspnetcorehosting) + * [Instrument: `http.server.request.duration`](#instrument-httpserverrequestduration) + * [Instrument: `http.server.active_requests`](#instrument-httpserveractive_requests) +- [Meter: `Microsoft.AspNetCore.Routing`](#meter-microsoftaspnetcorerouting) + * [Instrument: `aspnetcore.routing.match_attempts`](#instrument-aspnetcoreroutingmatch_attempts) +- [Meter: `Microsoft.AspNetCore.Diagnostics`](#meter-microsoftaspnetcorediagnostics) + * [Instrument: `aspnetcore.diagnostics.exceptions`](#instrument-aspnetcorediagnosticsexceptions) +- [Meter: `Microsoft.AspNetCore.RateLimiting`](#meter-microsoftaspnetcoreratelimiting) + * [Instrument: `aspnetcore.rate_limiting.active_request_leases`](#instrument-aspnetcorerate_limitingactive_request_leases) + * [Instrument: `aspnetcore.rate_limiting.request_lease.duration`](#instrument-aspnetcorerate_limitingrequest_leaseduration) + * [Instrument: `aspnetcore.rate_limiting.queued_requests`](#instrument-aspnetcorerate_limitingqueued_requests) + * [Instrument: `aspnetcore.rate_limiting.request.time_in_queue`](#instrument-aspnetcorerate_limitingrequesttime_in_queue) + * [Instrument: `aspnetcore.rate_limiting.requests`](#instrument-aspnetcorerate_limitingrequests) +- [Meter: `Microsoft.AspNetCore.Server.Kestrel`](#meter-microsoftaspnetcoreserverkestrel) + * [Instrument: `kestrel.active_connections`](#instrument-kestrelactive_connections) + * [Instrument: `kestrel.connection.duration`](#instrument-kestrelconnectionduration) + * [Instrument: `kestrel.rejected_connections`](#instrument-kestrelrejected_connections) + * [Instrument: `kestrel.queued_connections`](#instrument-kestrelqueued_connections) + * [Instrument: `kestrel.queued_requests`](#instrument-kestrelqueued_requests) + * [Instrument: `kestrel.upgraded_connections`](#instrument-kestrelupgraded_connections) + * [Instrument: `kestrel.tls_handshake.duration`](#instrument-kestreltls_handshakeduration) + * [Instrument: `kestrel.active_tls_handshakes`](#instrument-kestrelactive_tls_handshakes) +- [Meter: `Microsoft.AspNetCore.Http.Connections`](#meter-microsoftaspnetcorehttpconnections) + * [Instrument: `signalr.server.connection.duration`](#instrument-signalrserverconnectionduration) + * [Instrument: `signalr.server.active_connections`](#instrument-signalrserveractive_connections) + +## Meter: `Microsoft.AspNetCore.Hosting` + +### Instrument: `http.server.request.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.request.duration` | Histogram | `s` | Measures the duration of inbound HTTP requests. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.route` | string | The matched route. | `{controller}/{action}/{id?}` | If it's available. | +| `error.type` | string | Describes a class of error the operation ended with. | `timeout`; `name_resolution_error`; `500` | If request has ended with an error. | +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was sent. | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. | `amqp`; `http`; `mqtt` | Always | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. | `3.1.1` | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | +| `aspnetcore.request.is_unhandled` | boolean | True when the request wasn't handled by the application pipeline. | `true` | If the request was unhandled. | + +The time used to handle an inbound HTTP request as measured at the hosting layer of ASP.NET Core. The time measurement starts once the underlying web host has: + +- Sufficiently parsed the HTTP request headers on the inbound network stream to identify the new request. +- Initialized the context data structures such as the . + +The time ends when: + +- The ASP.NET Core handler pipeline is finished executing. +- All response data has been sent. +- The context data structures for the request are being disposed. + + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `http.server.active_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.server.active_requests` | UpDownCounter | `{request}` | Measures the number of concurrent HTTP requests that are currently in-flight. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Always | +| `url.scheme`| string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Always | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Routing` + +### Instrument: `aspnetcore.routing.match_attempts` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.routing.match_attempts` | Counter | `{match_attempt}` | Number of requests that were attempted to be matched to an endpoint. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.routing.match_status` | string | Match result | `success`; `failure` | Always | +| `aspnetcore.routing.is_fallback_route` | boolean | A value that indicates whether the matched route is a fallback route. | `True` | If a route was successfully matched. | +| `http.route` | string | The matched route | `{controller}/{action}/{id?}` | If a route was successfully matched. | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Diagnostics` + +### Instrument: `aspnetcore.diagnostics.exceptions` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.diagnostics.exceptions` | Counter | `{exception}` | Number of exceptions caught by exception handling middleware. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.diagnostics.exception.result` | string | ASP.NET Core exception middleware handling result | `handled`; `unhandled` | Always | +| `aspnetcore.diagnostics.handler.type` | string | Full type name of the [`IExceptionHandler`](https://learn.microsoft.com/dotnet/api/microsoft.aspnetcore.diagnostics.iexceptionhandler) implementation that handled the exception. | `Contoso.MyHandler` | If the exception was handled by this handler. | +| `exception.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | Always | + +`aspnetcore.diagnostics.exception.result` is one of the following: + +| Value | Description | +|---|---| +| `handled` | Exception was handled by the exception handling middleware. | +| `unhandled` | Exception wasn't handled by the exception handling middleware. | +| `skipped` | Exception handling was skipped because the response had started. | +| `aborted` | Exception handling didn't run because the request was aborted. | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.RateLimiting` + +### Instrument: `aspnetcore.rate_limiting.active_request_leases` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.active_request_leases` | UpDownCounter | `{request}` | Number of requests that are currently active on the server that hold a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.request_lease.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.request_lease.duration` | Histogram | `s` | The duration of the rate limiting lease held by requests on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.queued_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.queued_requests` | UpDownCounter | `{request}` | Number of requests that are currently queued waiting to acquire a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.request.time_in_queue` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.request.time_in_queue` | Histogram | `s` | The time a request spent in a queue waiting to acquire a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | +| `aspnetcore.rate_limiting.result` | string | The rate limiting result shows whether lease was acquired or contains a rejection reason. | `acquired`; `request_canceled` | Always | + +`aspnetcore.rate_limiting.result` is one of the following: + +| Value | Description | +|---|---| +| `acquired` | Lease was acquired | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `aspnetcore.rate_limiting.requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `aspnetcore.rate_limiting.requests` | Counter | `{request}` | Number of requests that tried to acquire a rate limiting lease. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `aspnetcore.rate_limiting.policy` | string | Rate limiting policy name. | `fixed`; `sliding`; `token` | If the matched endpoint for the request had a rate-limiting policy. | +| `aspnetcore.rate_limiting.result` | string | The rate limiting result shows whether lease was acquired or contains a rejection reason. | `acquired`; `request_canceled` | Always | + +`aspnetcore.rate_limiting.result` is one of the following: + +| Value | Description | +|---|---| +| `acquired` | Lease was acquired | +| `endpoint_limiter` | Lease request was rejected by the endpoint limiter | +| `global_limiter` | Lease request was rejected by the global limiter | +| `request_canceled` | Lease request was canceled | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Server.Kestrel` + +### Instrument: `kestrel.active_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.type`| string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port`| int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.connection.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.connection.duration` | Histogram | `s` | The duration of connections on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | If an exception was thrown. | +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. | `http`; `web_sockets` | Always | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. | `1.1`; `2` | Always | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | +| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | If the connection is secured with TLS. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.rejected_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.rejected_connections` | Counter | `{connection}` | Number of connections rejected by the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport`| string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address`| string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Connections are rejected when the currently active count exceeds the value configured with `MaxConcurrentConnections`. + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.queued_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_connections` | UpDownCounter | `{connection}` | Number of connections that are currently queued and are waiting to start. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.queued_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.queued_requests` | UpDownCounter | `{request}` | Number of HTTP requests on multiplexed connections (HTTP/2 and HTTP/3) that are currently queued and are waiting to start. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. | `http`; `web_sockets` | Always | +| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. | `1.1`; `2` | Always | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.upgraded_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.upgraded_connections` | UpDownCounter | `{connection}` | Number of connections that are currently upgraded (WebSockets). | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +The counter only tracks HTTP/1.1 connections. + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.tls_handshake.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.tls_handshake.duration` | Histogram | `s` | The duration of TLS handshakes on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `error.type` | string | The full name of exception type. | `System.OperationCanceledException`; `Contoso.MyException` | If an exception was thrown. | +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | +| `tls.protocol.version` | string | TLS protocol version. | `1.2`; `1.3` | If the connection is secured with TLS. | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `kestrel.active_tls_handshakes` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `kestrel.active_tls_handshakes` | UpDownCounter | `{handshake}` | Number of TLS handshakes that are currently in progress on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). | `tcp`; `unix` | Always | +| `network.transport` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. | `ipv4`; `ipv6` | If the transport is `tcp` or `udp`. | +| `server.address` | string | Server address domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. | `example.com` | Always | +| `server.port` | int | Server port number | `80`; `8080`; `443` | If the transport is `tcp` or `udp`. | + +Available staring in: ASP.NET Core 8.0 + +## Meter: `Microsoft.AspNetCore.Http.Connections` + +### Instrument: `signalr.server.connection.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.connection.duration` | Histogram | `s` | The duration of connections on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Always | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Always | + +`signalr.connection.status` is one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`signalr.transport` is one of the following: + +| Value | Protocol | +|---|---| +| `server_sent_events` | [server-sent events](https://developer.mozilla.org/docs/Web/API/Server-sent_events/Using_server-sent_events) | +| `long_polling` | [Long Polling](/archive/msdn-magazine/2012/april/cutting-edge-long-polling-and-signalr) | +| `web_sockets` | [WebSocket](https://datatracker.ietf.org/doc/html/rfc6455) | + +Available staring in: ASP.NET Core 8.0 + +### Instrument: `signalr.server.active_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `signalr.server.active_connections` | UpDownCounter | `{connection}` | Number of connections that are currently active on the server. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `signalr.connection.status` | string | SignalR HTTP connection closure status. | `app_shutdown`; `timeout` | Always | +| `signalr.transport` | string | [SignalR transport type](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/docs/specs/TransportProtocols.md) | `web_sockets`; `long_polling` | Always | + +`signalr.connection.status` is one of the following: + +| Value | Description | +|---|---| +| `normal_closure` | The connection was closed normally. | +| `timeout` | The connection was closed due to a timeout. | +| `app_shutdown` | The connection was closed because the app is shutting down. | + +`signalr.transport` is one of the following: + +| Value | Description | +|---|---| +| `server_sent_events` | ServerSentEvents protocol | +| `long_polling` | LongPolling protocol | +| `web_sockets` | WebSockets protocol | + +Available staring in: ASP.NET Core 8.0 diff --git a/docs/core/diagnostics/built-in-metrics-system-net.md b/docs/core/diagnostics/built-in-metrics-system-net.md new file mode 100644 index 0000000000000..d45a2ed1a882a --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics-system-net.md @@ -0,0 +1,151 @@ +--- +title: System.Net Metrics +description: Review the metrics available for System.Net +ms.topic: reference +ms.date: 9/21/2023 +--- + +# System.Net Metrics + +This article describes the networking metrics built-in for produced using the + API. For a listing of metrics based on the alternate [EventCounters](event-counters.md) API, +see [here](available-counters.md). + +- [Meter: `System.Net.NameResolution`](#meter-systemnetnameresolution) - Metrics for DNS lookups + * [Instrument: `dns.lookup.duration`](#instrument-dnslookupduration) +- [Meter: `System.Net.Http`](#meter-systemnethttp) - Metrics for outbound networking requests using HttpClient + * [Instrument: `http.client.open_connections`](#instrument-httpclientopen_connections) + * [Instrument: `http.client.connection.duration`](#instrument-httpclientconnectionduration) + * [Instrument: `http.client.request.duration`](#instrument-httpclientrequestduration) + * [Instrument: `http.client.request.time_in_queue`](#instrument-httpclientrequesttime_in_queue) + * [Instrument: `http.client.active_requests`](#instrument-httpclientactive_requests) + +## Meter: `System.Net.NameResolution` + +### Instrument: `dns.lookup.duration` + +| Name | Instrument Type | Unit | Description | +| -------- | --------------- | ----------- | -------------- | +| `dns.lookup.duration` | Histogram | `s` | Measures the time taken to perform a DNS lookup. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `dns.question.name` | string | The name being queried. | `www.example.com`; `dot.net` | Always | +| `error.type` | string | A well-known error string or the full type name of an exception that occured. | `host_not_found`; `System.Net.Sockets.SocketException` | If an error occured | + +This metric measures the time take to make DNS requests. These requests can occur by calling methods on + or indirectly wihtin higher level APIs on types such as . + +Most errors when doing a DNS lookup throw a . To better disambiguate the common error cases, SocketExceptions with specific +are given explicit error names in `error.type`: + +| SocketErrorCode | `error.type` | +| --------------- | ------------ | +| | host_not_found | +| | try_again | +| | address_family_not_supported | +| | no_recovery | + +SocketExceptions with any other SocketError value are reported as `System.Net.Sockets.SocketException`. + +Available starting in: .NET 8 + +## Meter: `System.Net.Http` + +### Instrument: `http.client.open_connections` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.open_connections` | UpDownCounter | `{connection}` | Number of outbound HTTP connections that are currently active or idle on the client | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.connection.state` | string | State of HTTP connection in the HTTP connection pool. | `active`; `idle` | Always | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `network.peer.address` | string | Peer IP address of the socket connection. | `10.5.3.2` | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +, when configured to use the default , maintains a cached pool of network connections for sending HTTP messages. This metric counts how many connections are currently +in the pool. Active connections are handling active requests. Active connects could be transmitting data or awaiting the client or server. Idle connections aren't handling any +requests, but are left open so that future requests can be handled more quickly. + +Available starting in: .NET 8 + +### Instrument: `http.client.connection.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.connection.duration` | Histogram | `s` | The duration of successfully established outbound HTTP connections. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `network.peer.address` | string | IP address of the socket connection. | `10.5.3.2` | Always | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +This metric is only captured when is configured to use the default . + +Available starting in: .NET 8 + +### Instrument: `http.client.request.duration` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.duration` | Histogram | `s` | The duration of outbound HTTP requests. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.error.reason` | string | Request failure reason: one of [HTTP Request errors](https://github.com/dotnet/runtime/blob/c430570a01c103bc7f117be573f37d8ce8a129b8/src/libraries/System.Net.Http/src/System/Net/Http/HttpRequestError.cs), or a full exception type, or an HTTP 4xx/5xx status code. | `System.Threading.Tasks.TaskCanceledException`; `name_resolution_error`; `secure_connection_error` ; `404` | If request has failed. | +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was received. | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +HTTP client request duration measures the time the underlying client handler takes to complete the request up to reading response headers from the network +stream. It does not include the time spent reading the response body. + +Available starting in: .NET 8 + +### Instrument: `http.client.request.time_in_queue` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.request.time_in_queue` | Histogram | `s` | The amount of time requests spent on a queue waiting for an available connection. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +, when configured to use the default , sends HTTP requests using a pool of network connections. +If all connections are already busy handling other requests, new requests are placed in a queue and wait until a network connection is available for use. This instrument +measures the amount of time HTTP requests spend waiting in that queue, prior to anything being sent across the network. + +Available starting in: .NET 8 + +### Instrument: `http.client.active_requests` + +| Name | Instrument Type | Unit (UCUM) | Description | +| -------- | --------------- | ----------- | -------------- | +| `http.client.active_requests` | UpDownCounter | `{request}` | Number of active HTTP requests. | + +| Attribute | Type | Description | Examples | Presence | +|---|---|---|---|---| +| `http.request.method` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Always | +| `network.protocol.version` | string | Version of the application layer protocol used. | `1.1`; `2` | Always | +| `server.address` | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `example.com` | Always | +| `server.port` | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. | `80`; `8080`; `443` | If not default (`80` for `http` scheme, `443` for `https`) | +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https`; `ftp` | Always | + +This metric counts how many requests are considered active. Requests are active for the same time period that is measured by the [http.client.request.duration](#instrument-httpclientrequestduration) instrument. + +Available starting in: .NET 8 diff --git a/docs/core/diagnostics/built-in-metrics.md b/docs/core/diagnostics/built-in-metrics.md new file mode 100644 index 0000000000000..88126da3da619 --- /dev/null +++ b/docs/core/diagnostics/built-in-metrics.md @@ -0,0 +1,15 @@ +--- +title: Built-in Metrics in .NET +description: Review the metrics built-in for the .NET runtime and libraries. +ms.topic: reference +ms.date: 9/21/2023 +--- + +# Built-in Metrics in .NET + +This is a reference for [metrics](metrics.md) built-in for .NET, produced using the + API. For metrics produced by [alternative metric APIs](compare-metric-apis.md) +see the [EventCounters reference](available-counters.md) and [Windows Performance Counter reference](../../framework/debug-trace-profile/performance-counters.md). + +- [ASP.NET Core Metrics](built-in-metrics-aspnetcore.md) +- [System.Net Metrics](built-in-metrics-system-net.md) diff --git a/docs/core/diagnostics/compare-metric-apis.md b/docs/core/diagnostics/compare-metric-apis.md index 38443f7d5f14b..50044cfbca558 100644 --- a/docs/core/diagnostics/compare-metric-apis.md +++ b/docs/core/diagnostics/compare-metric-apis.md @@ -29,11 +29,10 @@ Over .NET's 20+ year history, we've iterated a few times on the design for metri ### System.Diagnostics.Metrics [System.Diagnostics.Metrics](metrics-instrumentation.md) APIs are the newest cross-platform APIs, and were designed in close collaboration with the -[OpenTelemetry](https://opentelemetry.io/) project. The OpenTelemetry effort is an industry-wide collaboration across telemetry tooling vendors, -programming languages, and application developers to create a broadly compatible standard for telemetry APIs. To eliminate any friction associated with adding third-party dependencies, .NET embeds the metrics API directly into the base class libraries. -It's available by targeting .NET 6, or in older .NET Core and .NET Framework apps by adding a reference to the .NET -[System.Diagnostics.DiagnosticsSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource) 6.0 NuGet package. In addition to -aiming at broad compatibility, this API adds support for many things that were lacking from EventCounters, such as: +[OpenTelemetry](https://opentelemetry.io/) project. If you don't have a specific reason to use one of the older APIs covered below, [System.Diagnostics.Metrics](metrics-instrumentation.md) is +a good default choice for new work. It's available by targeting .NET 6+, or in older .NET Core and .NET Framework apps by adding a reference to the .NET +[System.Diagnostics.DiagnosticsSource](https://www.nuget.org/packages/System.Diagnostics.DiagnosticSource) 6.0+ NuGet package. In addition to +aiming at broad compatibility, this API adds support for many things that were lacking from earlier APIs, such as: - Histograms and percentiles - Multi-dimensional metrics @@ -41,7 +40,7 @@ aiming at broad compatibility, this API adds support for many things that were l - Multiple simultaneous listeners - Listener access to unaggregated measurements -Although this API was designed to work well with OpenTelemetry and its growing ecosystem of pluggable vendor integration libraries, applications also have the option to use the .NET built-in listener APIs directly. With this option, you can create custom metric tooling without taking any external library dependencies. At the time of writing, the [System.Diagnostics.Metrics](xref:System.Diagnostics.Metrics) support is limited to [dotnet-counters](dotnet-counters.md) and [OpenTelemetry.NET](https://opentelemetry.io/docs/net/). However, we expect support for these APIs will grow given the active nature of the OpenTelemetry project. +Although this API was designed to work well with OpenTelemetry and its growing ecosystem of pluggable vendor integration libraries, applications also have the option to use the .NET built-in listener APIs directly. With this option, you can create custom metric tooling without taking any external library dependencies. ### PerformanceCounter @@ -68,10 +67,8 @@ access to the aggregated values, and has limitations when using more than one li [dotnet-counters](dotnet-counters.md), and [dotnet-monitor](https://devblogs.microsoft.com/dotnet/introducing-dotnet-monitor/). For third-party tool support, check the vendor or project documentation to see if it's available. -At the time of writing, this is the cross-platform .NET runtime API that has the broadest and most stable ecosystem support. However, it will likely be -overtaken soon by growing support for [System.Diagnostics.Metrics](metrics-instrumentation.md). The .NET team doesn't expect to -make substantial new investments on this API going forward, but as with `PerformanceCounters`, the API remains actively supported for all -current and future users. +The .NET team doesn't expect to make substantial new investments on this API going forward, but as with `PerformanceCounters`, the API remains +actively supported for all current and future users. ## Third-party APIs diff --git a/docs/core/diagnostics/metrics-collection.md b/docs/core/diagnostics/metrics-collection.md index 9214ef1aa2cad..36bce770d8fb7 100644 --- a/docs/core/diagnostics/metrics-collection.md +++ b/docs/core/diagnostics/metrics-collection.md @@ -23,7 +23,7 @@ For more information on custom metric instrumentation and options, see [Compare ## Create an example app -Before metrics can be collected, measurements must be produced. This tutorial creates an app that has basic metric instrumentation. The .NET runtime also has [various metrics built-in](available-counters.md). For more information about creating new metrics using the API, see [the instrumentation tutorial](metrics-instrumentation.md). +Before metrics can be collected, measurements must be produced. This tutorial creates an app that has basic metric instrumentation. The .NET runtime also has [various metrics built-in](built-in-metrics.md). For more information about creating new metrics using the API, see [the instrumentation tutorial](metrics-instrumentation.md). ```dotnetcli dotnet new console -o metric-instr @@ -97,7 +97,7 @@ Press p to pause, r to resume, q to quit. Working Set (MB) 30 ``` -For more information, see [dotnet-counters](dotnet-counters.md). To learn more about metrics in .NET, see [built-in metrics](available-counters.md). +For more information, see [dotnet-counters](dotnet-counters.md). To learn more about metrics in .NET, see [built-in metrics](built-in-metrics.md). ## View metrics in Grafana with OpenTelemetry and Prometheus diff --git a/docs/core/diagnostics/metrics.md b/docs/core/diagnostics/metrics.md index 6631195ba2e42..a31648369da02 100644 --- a/docs/core/diagnostics/metrics.md +++ b/docs/core/diagnostics/metrics.md @@ -28,6 +28,6 @@ There are two parts to using metrics in a .NET app: - [Instrumentation tutorial](metrics-instrumentation.md) - How to create new metrics in code - [Collection tutorial](metrics-collection.md) - How to store and view metric data for your app -- [Built-in metrics](available-counters.md) - Discover metrics that are ready for use in .NET runtime libraries +- [Built-in metrics](built-in-metrics.md) - Discover metrics that are ready for use in .NET runtime libraries - [Compare metric APIs](compare-metric-apis.md) - [EventCounters](event-counters.md) - Learn what EventCounters are, how to implement them, and how to consume them diff --git a/docs/core/diagnostics/observability-with-otel.md b/docs/core/diagnostics/observability-with-otel.md index 3211a53ef66b7..7c0f5cbe28722 100644 --- a/docs/core/diagnostics/observability-with-otel.md +++ b/docs/core/diagnostics/observability-with-otel.md @@ -7,7 +7,7 @@ ms.topic: conceptual # .NET observability with OpenTelemetry -When you run an application, you want to know how well the app is performing and to detect potential problems before they become larger. Commonly developers accomplish this by making the app emit telemetry data such as logs or metrics, then monitor and analyze that data. +When you run an application, you want to know how well the app is performing and to detect potential problems before they become larger. You can do this by emitting telemetry data such as logs or metrics from your app, then monitoring and analyzing that data. ## What is observability @@ -19,7 +19,7 @@ Observability is commonly done using a combination of: - Metrics, which are measuring counters and gauges such as number of completed requests, active requests, widgets that have been sold; or a histogram of the request latency. - Distributed tracing, which tracks requests and activities across components in a distributed system so that you can see where time is spent and track down specific failures. -Together, logs, metrics, and distributed tracing are known as the *3 pillars of observability*. +Together, logs, metrics, and distributed tracing are known as the *three pillars of observability*. Each pillar might include telemetry data from: diff --git a/docs/core/extensions/httpclient-sni.md b/docs/core/extensions/httpclient-sni.md index e1a9379993c3f..60d35a286b51e 100644 --- a/docs/core/extensions/httpclient-sni.md +++ b/docs/core/extensions/httpclient-sni.md @@ -8,9 +8,9 @@ ms.date: 9/5/2023 # Customize SNI in HTTP requests -When negotiating an HTTPS connection, a TLS connection needs to be established first. As part of the TLS handshake, the client sends the domain name of the server it's connecting to in one of the TLS extensions. When hosting multiple (virtual) servers on the same machine, this feature of the TLS protocol allows clients to distinguish which of these servers they're connecting to and to configure TLS settings, such as the server certificate, accordingly. +When a client and server negotiate an HTTPS connection, a TLS connection needs to be established first. As part of the TLS handshake, the client sends the domain name of the server it's connecting to in one of the TLS extensions. When multiple (virtual) servers are hosted on the same machine, this feature of the TLS protocol allows clients to distinguish which of these servers they're connecting to and to configure TLS settings, such as the server certificate, accordingly. -When making an HTTP request using `HttpClient`, the implementation automatically selects a value for the server name indication (SNI) extension based on the URL the client is connecting to. For scenarios that require more manual control of the extension, you can use one of the following approaches. +When an HTTP request using `HttpClient` is made, the implementation automatically selects a value for the server name indication (SNI) extension based on the URL the client is connecting to. For scenarios that require more manual control of the extension, you can use one of the following approaches. ## Host header @@ -34,7 +34,7 @@ System.Console.WriteLine(response); ## Manual SslStream authentication via ConnectCallback -A more complicated, but also more powerful, option is to use the `SocketsHttpHandler.ConnectCallback`. Since .NET 7, it is possible to return an authenticated `SslStream` and thus customize how the TLS connection is established. Inside the callback, arbitrary `SslClientAuthenticationOptions` options can be used to perform client-side authentication. +A more complicated, but also more powerful, option is to use the `SocketsHttpHandler.ConnectCallback`. Since .NET 7, it's possible to return an authenticated `SslStream` and thus customize how the TLS connection is established. Inside the callback, arbitrary `SslClientAuthenticationOptions` options can be used to perform client-side authentication. ```csharp var handler = new SocketsHttpHandler diff --git a/docs/core/install/macos.md b/docs/core/install/macos.md index bd47b152636aa..211412bd99432 100644 --- a/docs/core/install/macos.md +++ b/docs/core/install/macos.md @@ -14,7 +14,7 @@ ms.date: 12/21/2022 > - [Install on macOS](macos.md) > - [Install on Linux](linux.md) -In this article, you'll learn how to install .NET on macOS. .NET is made up of the runtime and the SDK. The runtime is used to run a .NET app and may or may not be included with the app. The SDK is used to create .NET apps and libraries. The .NET runtime is always installed with the SDK. +In this article, you learn how to install .NET on macOS. .NET is made up of the runtime and the SDK. The runtime is used to run a .NET app and might or might not be included with the app. The SDK is used to create .NET apps and libraries. The .NET runtime is always installed with the SDK. The latest version of .NET is 7. @@ -23,7 +23,7 @@ The latest version of .NET is 7. ## Supported releases -There are two types of supported releases, Long Term Support (LTS) releases or Standard Term Support (STS). The quality of all releases is the same. The only difference is the length of support. LTS releases get free support and patches for 3 years. STS releases get free support and patches for 18 months. For more information, see [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). +There are two types of supported releases, Long Term Support (LTS) releases or Standard Term Support (STS). The quality of all releases is the same. The only difference is the length of support. LTS releases get free support and patches for three years. STS releases get free support and patches for 18 months. For more information, see [.NET Support Policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core). The following table is a list of currently supported .NET releases and the versions of macOS they're supported on: @@ -92,7 +92,7 @@ macOS has standalone installers that can be used to install .NET 7: As an alternative to the macOS installers for .NET, you can download and manually install the SDK and runtime. Manual installation is usually performed as part of continuous integration testing. For a developer or user, it's generally better to use an [installer](https://dotnet.microsoft.com/download/dotnet). -First, download a **binary** release for either the SDK or the runtime from one of the following sites. If you install the .NET SDK, you will not need to install the corresponding runtime: +First, download a **binary** release for either the SDK or the runtime from one of the following sites. If you install the .NET SDK, you won't need to install the corresponding runtime: - ✔️ [.NET 7 downloads](https://dotnet.microsoft.com/download/dotnet/7.0) - ✔️ [.NET 6 downloads](https://dotnet.microsoft.com/download/dotnet/6.0) @@ -101,7 +101,7 @@ First, download a **binary** release for either the SDK or the runtime from one Next, extract the downloaded file and use the `export` command to set `DOTNET_ROOT` to the extracted folder's location and then ensure .NET is in PATH. This should make the .NET CLI commands available at the terminal. For more information about .NET environment variables, see [.NET SDK and CLI environment variables](../tools/dotnet-environment-variables.md#net-sdk-and-cli-environment-variables). -Alternatively, after downloading the .NET binary, the following commands may be run from the directory where the file is saved to extract the runtime. This will also make the .NET CLI commands available at the terminal and set the required environment variables. **Remember to change the `DOTNET_FILE` value to the name of the downloaded binary**: +Alternatively, after downloading the .NET binary, the following commands can be run from the directory where the file is saved to extract the runtime. These commands also make the .NET CLI commands available at the terminal and set the required environment variables. **Remember to change the `DOTNET_FILE` value to the name of the downloaded binary**: ```bash DOTNET_FILE=dotnet-sdk-7.0.100-osx-x64.tar.gz @@ -158,11 +158,11 @@ On an Arm-based Mac, all Arm64 versions of .NET are installed to the normal _/us ### Path conflicts -Starting with .NET 6, the **x64** .NET SDK installs to its own directory, as described in the previous section. This allows the Arm64 and x64 versions of the .NET SDK to exist on the same machine. However, any **x64** SDK prior to .NET 6 isn't supported and installs to the same location as the Arm64 version, the _/usr/local/share/dotnet/_ folder. If you want to install an unsupported x64 SDK, you'll need to first uninstall the Arm64 version. The opposite is also true, you'll need to uninstall the unsupported x64 SDK to install the Arm64 version. +Starting with .NET 6, the **x64** .NET SDK installs to its own directory, as described in the previous section. This allows the Arm64 and x64 versions of the .NET SDK to exist on the same machine. However, any **x64** SDK prior to .NET 6 isn't supported and installs to the same location as the Arm64 version, the _/usr/local/share/dotnet/_ folder. If you want to install an unsupported x64 SDK, you need to first uninstall the Arm64 version. The opposite is also true, you need to uninstall the unsupported x64 SDK to install the Arm64 version. ### Path variables -Environment variables that add .NET to system path, such as the `PATH` variable, may need to be changed if you have both the x64 and Arm64 versions of the .NET 6 SDK installed. Additionally, some tools rely on the `DOTNET_ROOT` environment variable, which would also need to be updated to point to the appropriate .NET 6 SDK installation folder. +Environment variables that add .NET to system path, such as the `PATH` variable, might need to be changed if you have both the x64 and Arm64 versions of the .NET 6 SDK installed. Additionally, some tools rely on the `DOTNET_ROOT` environment variable, which would also need to be updated to point to the appropriate .NET 6 SDK installation folder. ## Install with Visual Studio for Mac diff --git a/docs/core/tools/sdk-errors/index.md b/docs/core/tools/sdk-errors/index.md index 8004ad051f2f8..75c2a1eb5ce91 100644 --- a/docs/core/tools/sdk-errors/index.md +++ b/docs/core/tools/sdk-errors/index.md @@ -169,7 +169,7 @@ f1_keywords: **This article applies to:** ✔️ .NET 6 SDK and later versions -This is a complete list of the errors that you might get from the .NET SDK while developing .NET apps. If more info is available for a particular error, the error number is a link. +This list is a complete list of the errors that you might get from the .NET SDK while developing .NET apps. If more info is available for a particular error, the error number is a link. | SDK Message Number | Message | |--------------------|--------------------| diff --git a/docs/csharp/advanced-topics/interface-implementation/default-interface-methods-versions.md b/docs/csharp/advanced-topics/interface-implementation/default-interface-methods-versions.md index dba13d7fd5169..f5c6b3367d733 100644 --- a/docs/csharp/advanced-topics/interface-implementation/default-interface-methods-versions.md +++ b/docs/csharp/advanced-topics/interface-implementation/default-interface-methods-versions.md @@ -33,7 +33,7 @@ From those interfaces, the team could build a library for their users to create Now, it's time to upgrade the library for the next release. One of the requested features enables a loyalty discount for customers that have lots of orders. This new loyalty discount gets applied whenever a customer makes an order. The specific discount is a property of each individual customer. Each implementation of `ICustomer` can set different rules for the loyalty discount. -The most natural way to add this functionality is to enhance the `ICustomer` interface with a method to apply any loyalty discount. This design suggestion caused concern among experienced developers: "Interfaces are immutable once they've been released! Don't make a breaking change!" *Default interface implementations* for upgrading interfaces. The library authors can add new members to the interface and provide a default implementation for those members. +The most natural way to add this functionality is to enhance the `ICustomer` interface with a method to apply any loyalty discount. This design suggestion caused concern among experienced developers: "Interfaces are immutable once they've been released! Don't make a breaking change!" You should use default interface implementations for upgrading interfaces. The library authors can add new members to the interface and provide a default implementation for those members. Default interface implementations enable developers to upgrade an interface while still enabling any implementors to override that implementation. Users of the library can accept the default implementation as a non-breaking change. If their business rules are different, they can override. diff --git a/docs/csharp/advanced-topics/performance/index.md b/docs/csharp/advanced-topics/performance/index.md index ee401bf918d85..a7e8e015b9660 100644 --- a/docs/csharp/advanced-topics/performance/index.md +++ b/docs/csharp/advanced-topics/performance/index.md @@ -1,8 +1,7 @@ --- title: Avoid memory allocations and data copies description: Performance work in .NET means removing allocations from your code. One technique is to change critical data structures from `class` to `struct`. That changes semantics and means more data is being copied. Learn how to minimize allocations while preserving semantics and avoid extra copies. -ms.date: 02/03/2023 -ms.technology: csharp-advanced-concepts +ms.date: 10/13/2023 --- # Reduce memory allocations using new C# features @@ -23,7 +22,7 @@ Variables in C# store *values*. In `struct` types, the value is the contents of In C#, parameters to methods are *passed by value*, and return values are *return by value*. The *value* of the argument is passed to the method. The *value* of the return argument is the return value. -The `ref`, `in`, or `out` modifier indicates that parameter is *passed by reference*. The *reference* to the storage location is passed to the method. Adding `ref` to the method signature means the return value is *returned by reference*. The *reference* to the storage location is the return value. +The `ref`, `in`, `ref readonly`, or `out` modifier indicates that the argument is *passed by reference*. A *reference* to the storage location is passed to the method. Adding `ref` to the method signature means the return value is *returned by reference*. A *reference* to the storage location is the return value. You can also use *ref assignment* to have a variable refer to another variable. A typical assignment copies the *value* of the right hand side to the variable on the left hand side of the assignment. A *ref assignment* copies the memory location of the variable on the right hand side to the variable on the left hand side. The `ref` now refers to the original variable: @@ -33,7 +32,9 @@ When you *assign* a variable, you change its *value*. When you *ref assign* a va You can work directly with the storage for values using `ref` variables, pass by reference, and ref assignment. Scope rules enforced by the compiler ensure safety when working directly with storage. -## Ref safe to escape scope +The `ref readonly` and `in` modifiers both indicate that the argument should be passed by reference and can't be reassigned in the method. The difference is that `ref readonly` indicates that the method uses the parameter as a variable. The method might capture the parameter, or it might return the parameter by readonly reference. In those cases, you should use the `ref readonly` modifier. Otherwise, the `in` modifier offers more flexibility. You don't need to add the `in` modifier to an argument for an `in` parameter, so you can update existing API signatures safely using the `in` modifier. The compiler issues a warning if you don't add either the `ref` or `in` modifier to an argument for a `ref readonly` parameter. + +## Ref safe context C# includes rules for `ref` expressions to ensure that a `ref` expression can't be accessed where the storage it refers to is no longer valid. Consider the following example: @@ -41,36 +42,36 @@ C# includes rules for `ref` expressions to ensure that a `ref` expression can't public ref int CantEscape() { int index = 42; - return ref index; // Error: index's ref safe to escape scope is the body of CantEscape + return ref index; // Error: index's ref safe context is the body of CantEscape } ``` -The compiler reports an error because you can't return a reference to a local variable from a method. The caller can't access the storage being referred to. The *ref safe to escape scope* defines the scope in which a `ref` expression is safe to access or modify. The following table lists the *ref safe to escape scopes* for variable types. `ref` fields can't be declared in a `class` or a non-ref `struct`, so those rows aren't in the table: +The compiler reports an error because you can't return a reference to a local variable from a method. The caller can't access the storage being referred to. The *ref safe context* defines the scope in which a `ref` expression is safe to access or modify. The following table lists the *ref safe contexts* for variable types. `ref` fields can't be declared in a `class` or a non-ref `struct`, so those rows aren't in the table: -| Declaration | *ref safe to escape scope* | -|-----------------------------|-------------------------------| -| non-ref local | block where local is declared | -| non-ref parameter | current method | -| `ref`, `in` parameter | calling method | -| `out` parameter | current method | -| `class` field | calling method | -| non-ref `struct` field | current method | -| `ref` field of `ref struct` | calling method | +| Declaration | *ref safe context* | +|---------------------------------------|-------------------------------| +| non-ref local | block where local is declared | +| non-ref parameter | current method | +| `ref`, `ref readonly`, `in` parameter | calling method | +| `out` parameter | current method | +| `class` field | calling method | +| non-ref `struct` field | current method | +| `ref` field of `ref struct` | calling method | -A variable can be `ref` returned if its *ref safe to escape scope* is the calling method. If its *ref safe to escape scope* is the current method or a block, `ref` return is disallowed. The following snippet shows two examples. A member field can be accessed from the scope calling a method, so a class or struct field's *ref safe to escape scope* is the calling method. The *ref safe to escape scope* for a parameter with the `ref`, or `in` modifiers is the entire method. Both can be `ref` returned from a member method: +A variable can be `ref` returned if its *ref safe context* is the calling method. If its *ref safe context* is the current method or a block, `ref` return is disallowed. The following snippet shows two examples. A member field can be accessed from the scope calling a method, so a class or struct field's *ref safe context* is the calling method. The *ref safe context* for a parameter with the `ref`, or `in` modifiers is the entire method. Both can be `ref` returned from a member method: :::code language="csharp" source="./snippets/ref-safety/EscapeScopes.cs" id="RefSafeToEscapeScopes"::: > [!NOTE] -> When the `in` modifier is applied to a parameter, that parameter can be returned by `ref readonly`, not `ref`. +> When the `ref readonly` or `in` modifier is applied to a parameter, that parameter can be returned by `ref readonly`, not `ref`. -The compiler ensures that a reference can't escape its *ref safe to escape scope*. You can use `ref` parameters, `ref return` and `ref` local variables safely because the compiler detects if you've accidentally written code where a `ref` expression could be accessed when its storage isn't valid. +The compiler ensures that a reference can't escape its *ref safe context*. You can use `ref` parameters, `ref return`, and `ref` local variables safely because the compiler detects if you've accidentally written code where a `ref` expression could be accessed when its storage isn't valid. -## Safe to escape scope and ref structs +## Safe context and ref structs -`ref struct` types require more rules to ensure they can be used safely. A `ref struct` type may include `ref` fields. That requires the introduction of a *safe to escape scope*. For most types, the *safe to escape scope* is the calling method. In other words, a value that's not a `ref struct` can always be returned from a method. +`ref struct` types require more rules to ensure they can be used safely. A `ref struct` type can include `ref` fields. That requires the introduction of a *safe context*. For most types, the *safe context* is the calling method. In other words, a value that's not a `ref struct` can always be returned from a method. -Informally, the *safe to escape scope* for a `ref struct` is the scope where all of its `ref` fields can be accessed. In other words, it's the intersection of the *ref safe to escape scopes* of all its `ref` fields. The following method returns a `ReadOnlySpan` to a member field, so its *safe to escape scope* is the method: +Informally, the *safe context* for a `ref struct` is the scope where all of its `ref` fields can be accessed. In other words, it's the intersection of the *ref safe context* of all its `ref` fields. The following method returns a `ReadOnlySpan` to a member field, so its *safe context* is the method: :::code language="csharp" source="./snippets/ref-safety/EscapeScopes.cs" id="SafeToEscapeScope"::: @@ -91,16 +92,16 @@ public Span M() ## Unify memory types -The introduction of and provide a unified model for working with memory. and provide readonly versions for accessing memory. They all provide an abstraction over a block of memory storing an array of similar elements. The difference is that `Span` and `ReadOnlySpan` are `ref struct` types whereas `Memory` and `ReadOnlyMemory` are `struct` types. Spans contain a `ref field`. Therefore instances of a span can't leave its *safe to escape scope*. The *safe to escape* scope of a `ref struct` is the *ref safe to escape scope* of its `ref field`. The implementation of `Memory` and `ReadOnlyMemory` remove this restriction. You use these types to directly access memory buffers. +The introduction of and provide a unified model for working with memory. and provide readonly versions for accessing memory. They all provide an abstraction over a block of memory storing an array of similar elements. The difference is that `Span` and `ReadOnlySpan` are `ref struct` types whereas `Memory` and `ReadOnlyMemory` are `struct` types. Spans contain a `ref field`. Therefore instances of a span can't leave its *safe context*. The *safe context* of a `ref struct` is the *ref safe context* of its `ref field`. The implementation of `Memory` and `ReadOnlyMemory` remove this restriction. You use these types to directly access memory buffers. ## Improve performance with ref safety Using these features to improve performance involves these tasks: -- *Avoid allocations*: When you change a type from a `class` to a `struct`, you change how it's stored. Local variables are stored on the stack. Members are stored inline when the container object is allocated. This change means fewer allocations and that decreases the work the garbage collector does. It may also decrease memory pressure so the garbage collector runs less often. +- *Avoid allocations*: When you change a type from a `class` to a `struct`, you change how it's stored. Local variables are stored on the stack. Members are stored inline when the container object is allocated. This change means fewer allocations and that decreases the work the garbage collector does. It might also decrease memory pressure so the garbage collector runs less often. - *Preserve reference semantics*: Changing a type from a `class` to a `struct` changes the semantics of passing a variable to a method. Code that modified the state of its parameters needs modification. Now that the parameter is a `struct`, the method is modifying a copy of the original object. You can restore the original semantics by passing that parameter as a `ref` parameter. After that change, the method modifies the original `struct` again. - *Avoid copying data*: Copying larger `struct` types can impact performance in some code paths. You can also add the `ref` modifier to pass larger data structures to methods by reference instead of by value. -- *Restrict modifications*: When a `struct` type is passed by reference, the called method could modify the state of the struct. You can replace the `ref` modifier with the `in` modifier to indicate that the argument can't be modified. You can also create `readonly struct` types or `struct` types with `readonly` members to provide more control over what members of a `struct` can be modified. +- *Restrict modifications*: When a `struct` type is passed by reference, the called method could modify the state of the struct. You can replace the `ref` modifier with the `ref readonly` or `in` modifiers to indicate that the argument can't be modified. Prefer `ref readonly` when the method captures the parameter or returns it by readonly reference. You can also create `readonly struct` types or `struct` types with `readonly` members to provide more control over what members of a `struct` can be modified. - *Directly manipulate memory*: Some algorithms are most efficient when treating data structures as a block of memory containing a sequence of elements. The `Span` and `Memory` types provide safe access to blocks of memory. None of these techniques require `unsafe` code. Used wisely, you can get performance characteristics from safe code that was previously only possible by using unsafe techniques. You can try the techniques yourself in the tutorial on [reducing memory allocations](ref-tutorial.md). diff --git a/docs/csharp/advanced-topics/performance/ref-tutorial.md b/docs/csharp/advanced-topics/performance/ref-tutorial.md index f8e577c1c06e8..715bc864c25b6 100644 --- a/docs/csharp/advanced-topics/performance/ref-tutorial.md +++ b/docs/csharp/advanced-topics/performance/ref-tutorial.md @@ -1,7 +1,7 @@ --- title: "Tutorial: Reduce memory allocations using struct data types and ref language features." description: Learn to remove allocations from your code. Make use of `struct` types for fewer allocations. Use the `ref` and `in` modifiers to avoid copies and enable or disable modification. Use `ref struct` types like `Span` to directly use memory efficiently. -ms.date: 01/27/2023 +ms.date: 10/13/2023 ms.technology: csharp-advanced-concepts --- # Tutorial: Reduce memory allocations with `ref` safety @@ -163,7 +163,7 @@ Let's look again at `DebounceMeasurement.AddMeasurement`. You should add the `in :::code language="csharp" source="./snippets/ref-tutorial/IntruderAlert-finished/DebounceMeasurement.cs" id="InArgument"::: -That saves one copy operation. The `in` parameter is a reference to the copy already created by the caller. You can also save a copy with the `TakeMeasurement` method in the `Room` type. This method illustrates how the compiler provides safety when you pass arguments by `ref`. The initial `TakeMeasurement` method in the `Room` type takes an argument of `Func`. If you try to add the `in` or `ref` modifier to that declaration, the compiler reports an error. You can't pass a `ref` argument to a lambda expression. The compiler can't guarantee that the called expression doesn't copy the reference. If the lambda expression *captures* the reference, the reference could have a lifetime longer than the value it refers to. Accessing it outside its *ref safe to escape scope* would result in memory corruption. The `ref` safety rules don't allow it. You can learn more in the overview of [ref safety features](index.md#ref-safe-to-escape-scope). +That saves one copy operation. The `in` parameter is a reference to the copy already created by the caller. You can also save a copy with the `TakeMeasurement` method in the `Room` type. This method illustrates how the compiler provides safety when you pass arguments by `ref`. The initial `TakeMeasurement` method in the `Room` type takes an argument of `Func`. If you try to add the `in` or `ref` modifier to that declaration, the compiler reports an error. You can't pass a `ref` argument to a lambda expression. The compiler can't guarantee that the called expression doesn't copy the reference. If the lambda expression *captures* the reference, the reference could have a lifetime longer than the value it refers to. Accessing it outside its *ref safe context* would result in memory corruption. The `ref` safety rules don't allow it. You can learn more in the overview of [ref safety features](index.md#ref-safe-context). ## Preserve semantics diff --git a/docs/fsharp/language-reference/functions/external-functions.md b/docs/fsharp/language-reference/functions/external-functions.md index 2a8e7318c1093..99f08fca914cc 100644 --- a/docs/fsharp/language-reference/functions/external-functions.md +++ b/docs/fsharp/language-reference/functions/external-functions.md @@ -5,7 +5,7 @@ ms.date: 05/16/2016 --- # External Functions -This topic describes F# language support for calling functions in native code. +This article describes F# language support for calling functions in native code. ## Syntax @@ -16,7 +16,7 @@ extern declaration ## Remarks -In the previous syntax, *arguments* represents arguments that are supplied to the `System.Runtime.InteropServices.DllImportAttribute` attribute. The first argument is a string that represents the name of the DLL that contains this function, without the .dll extension. Additional arguments can be supplied for any of the public properties of the `System.Runtime.InteropServices.DllImportAttribute` class, such as the calling convention. +In the previous syntax, `arguments` represents arguments that are supplied to the `System.Runtime.InteropServices.DllImportAttribute` attribute. The first argument is a string that represents the name of the DLL that contains this function, without the .dll extension. Additional arguments can be supplied for any of the public properties of the `System.Runtime.InteropServices.DllImportAttribute` class, such as the calling convention. Assume you have a native C++ DLL that contains the following exported function. @@ -44,20 +44,20 @@ Interoperability with native code is referred to as *platform invoke* and is a f ### Defining Parameters in External Functions -When declaring external functions with return values or parameters you use a syntax similar to C. You have the option to use the managed (where the CLR will perform some automatic conversions between native and .NET types) and unmanaged declarations which may offer better performance in some circumstances. Take the example of the Windows function [GetBinaryTypeW](/windows/win32/api/winbase/nf-winbase-getbinarytypew). It can be declared in two different ways: +When you declare external functions with return values or parameters, you use a syntax similar to C. You have the option to use the managed declarations (where the CLR will perform some automatic conversions between native and .NET types) and unmanaged declarations, which might offer better performance in some circumstances. For example, the Windows function [GetBinaryTypeW](/windows/win32/api/winbase/nf-winbase-getbinarytypew) can be declared in two different ways: ```fs // Using automatic marshaling of managed types -[] extern bool GetBinaryTypeW([] string lpApplicationName, uint& lpBinaryType); ``` -`MarshalAs(UnmanagedType.LPWStr)` instructs the CLR to perform an automatic conversion between a .NET `string` and Windows native string representation when the function is called. `uint&` declares a `uint` that will be passed `byref` i.e. as a managed pointer. To obtain a managed pointer you use the address of `&` operator. +`MarshalAs(UnmanagedType.LPWStr)` instructs the CLR to perform an automatic conversion between a .NET `string` and Windows native string representation when the function is called. `uint&` declares a `uint` that will be passed `byref`, that is, as a managed pointer. To obtain a managed pointer, you use the address of `&` operator. -Alternately, you may wish to manage the marshalling of data types manually and declare the external functions using only [unmanaged types](../../../csharp/language-reference/builtin-types/unmanaged-types.md). +Alternately, you might want to manage the marshalling of data types manually and declare the external functions using only [unmanaged types](../../../csharp/language-reference/builtin-types/unmanaged-types.md). ```fs // Using unmanaged types @@ -67,7 +67,7 @@ extern int GetBinaryTypeW(nativeint lpApplicationName, uint* lpBinaryType); You could use to convert a .NET string to native format and receive a pointer (`nativeint`) to it that could be supplied to `lpApplicationName`. -To obtain a pointer to an integer you would use the pointer of `&&` operator or the [`fixed`](../fixed.md) keyword. +To obtain a pointer to an integer, use the pointer of `&&` operator or the [`fixed`](../fixed.md) keyword. ## See also diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index a7c10d6fd6551..3afc763061f7e 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -332,6 +332,14 @@ items: href: ../../core/diagnostics/metrics-instrumentation.md - name: Collection href: ../../core/diagnostics/metrics-collection.md + - name: Built-in Metrics + items: + - name: Overview + href: ../../core/diagnostics/built-in-metrics.md + - name: ASP.NET Core Metrics + href: ../../core/diagnostics/built-in-metrics-aspnetcore.md + - name: System.Net Metrics + href: ../../core/diagnostics/built-in-metrics-system-net.md - name: EventCounters items: - name: Overview diff --git a/docs/orleans/grains/index.md b/docs/orleans/grains/index.md index 716fb71311728..0683b4398817d 100644 --- a/docs/orleans/grains/index.md +++ b/docs/orleans/grains/index.md @@ -1,7 +1,7 @@ --- title: Develop a grain description: Learn how to develop a grain in .NET Orleans. -ms.date: 05/05/2023 +ms.date: 10/16/2023 --- # Develop a grain @@ -20,7 +20,9 @@ The following is an excerpt from the Orleans version 1.5 Presence Service sample public interface IPlayerGrain : IGrainWithGuidKey { Task GetCurrentGame(); + Task JoinGame(IGameGrain game); + Task LeaveGame(IGameGrain game); } @@ -58,6 +60,35 @@ public class PlayerGrain : Grain, IPlayerGrain } ``` +## Response timeout for grain methods + +The Orleans runtime allows you to enforce a response timeout per grain method. If a grain method doesn't complete within the timeout, the runtime throws the . To impose a response timeout, add the `ResponseTimeoutAttribute` to the interface's grain method definition. It's very important that the attribute is added to the interface method definition, not to the method implementation in the grain class, as both the client and the silo need to be aware of the timeout. + +Extending the previous `PlayerGrain` implementation, the following example shows how to impose a response timeout on the `LeaveGame` method: + +```csharp +public interface IPlayerGrain : IGrainWithGuidKey +{ + Task GetCurrentGame(); + + Task JoinGame(IGameGrain game); + + [ResponseTimeout("00:00:05")] // 5s timeout + Task LeaveGame(IGameGrain game); +} +``` + +The preceding code sets a response timeout of five seconds on the `LeaveGame` method. When leaving a game, if it takes longer than five seconds a is thrown. + +### Configure response timeout + +Much like individual grain method response timeouts, you can configure a default response timeout for all grain methods. Calls to grain methods will timeout if a response isn't received within a specified time period. By default, this period is **30 seconds**. You can configure the default response timeout: + +- By configuring on , on an external client. +- By configuring on , on a server. + +For more information on configuring Orleans, see [Client configuration](../host/configuration-guide/client-configuration.md) or [Server configuration](../host/configuration-guide/server-configuration.md). + ## Return values from grain methods A grain method that returns a value of type `T` is defined in a grain interface as returning a `Task`. diff --git a/includes/migration-guide/retargeting/networking/tls-1x-by-default-passes-schsendauxrecord-flag-underlying-schannel-api.md b/includes/migration-guide/retargeting/networking/tls-1x-by-default-passes-schsendauxrecord-flag-underlying-schannel-api.md index 77f55ba1c3728..46e28cf6c2353 100644 --- a/includes/migration-guide/retargeting/networking/tls-1x-by-default-passes-schsendauxrecord-flag-underlying-schannel-api.md +++ b/includes/migration-guide/retargeting/networking/tls-1x-by-default-passes-schsendauxrecord-flag-underlying-schannel-api.md @@ -2,7 +2,7 @@ #### Details -When using TLS 1.x, the .NET Framework relies on the underlying Windows SCHANNEL API. Starting with .NET Framework 4.6, the [SCH_SEND_AUX_RECORD](/windows/win32/api/schannel/ns-schannel-schannel_cred) flag is passed by default to SCHANNEL. This causes SCHANNEL to split data to be encrypted into two separate records, the first as a single byte and the second as *n*-1 bytes.In rare cases, this breaks communication between clients and existing servers that make the assumption that the data resides in a single record. +When using TLS 1.x, the .NET Framework relies on the underlying Windows SCHANNEL API. Starting with .NET Framework 4.6, the [SCH_SEND_AUX_RECORD](/windows/win32/api/schannel/ns-schannel-schannel_cred) flag is passed by default to SCHANNEL. This causes SCHANNEL to split data to be encrypted into two separate records, the first as a single byte and the second as *n*-1 bytes. In rare cases, this breaks communication between clients and existing servers that make the assumption that the data resides in a single record. #### Suggestion diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/GroupQueryResults.cs b/samples/snippets/csharp/concepts/linq/LinqSamples/GroupQueryResults.cs index 6b2dc6e41b42a..6d6f7285f244a 100644 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/GroupQueryResults.cs +++ b/samples/snippets/csharp/concepts/linq/LinqSamples/GroupQueryResults.cs @@ -197,16 +197,16 @@ public static void GroupQueryResults5() from student in students group student by new { - FirstLetter = student.LastName[0], + FirstLetterOfLastName = student.LastName[0], IsScoreOver85 = student.ExamScores[0] > 85 } into studentGroup - orderby studentGroup.Key.FirstLetter + orderby studentGroup.Key.FirstLetterOfLastName select studentGroup; foreach (var scoreGroup in groupByCompoundKey) { string s = scoreGroup.Key.IsScoreOver85 == true ? "more than 85" : "less than 85"; - Console.WriteLine($"Name starts with {scoreGroup.Key.FirstLetter} who scored {s}"); + Console.WriteLine($"Name starts with {scoreGroup.Key.FirstLetterOfLastName} who scored {s}"); foreach (var item in scoreGroup) { Console.WriteLine($"\t{item.FirstName} {item.LastName}");