diff --git a/.github/workflows/clean-repo.yml b/.github/workflows/clean-repo.yml index 8f635924ecf33..266be8f95bb50 100644 --- a/.github/workflows/clean-repo.yml +++ b/.github/workflows/clean-repo.yml @@ -39,7 +39,7 @@ jobs: # Create the PR for the work done by the "clean repo" tool - name: create-pull-request - uses: peter-evans/create-pull-request@70a41aba780001da0a30141984ae2a0c95d8704e + uses: peter-evans/create-pull-request@9153d834b60caba6d51c9b9510b087acf9f33f83 with: branch: create-cleanrepo-pull-request/patch title: "Monthly chores: Automated repo cleanup" diff --git a/.github/workflows/dependabot-bot.yml b/.github/workflows/dependabot-bot.yml index a83c7e2793775..44e0615107ef6 100644 --- a/.github/workflows/dependabot-bot.yml +++ b/.github/workflows/dependabot-bot.yml @@ -44,7 +44,7 @@ jobs: dependabot-yml-path: ".github/dependabot.yml" - name: Create pull request if: github.event_name == 'workflow_dispatch' || github.repository_owner == 'dotnet' - uses: peter-evans/create-pull-request@70a41aba780001da0a30141984ae2a0c95d8704e + uses: peter-evans/create-pull-request@9153d834b60caba6d51c9b9510b087acf9f33f83 with: branch: create-dependabotconfig-pull-request/patch title: "Update dependabot.yml - automatically." diff --git a/.github/workflows/whats-new.yml b/.github/workflows/whats-new.yml index e4852920d897c..449c35e883320 100644 --- a/.github/workflows/whats-new.yml +++ b/.github/workflows/whats-new.yml @@ -35,7 +35,7 @@ jobs: savedir: './docs/whats-new' - name: create-pull-request - uses: peter-evans/create-pull-request@70a41aba780001da0a30141984ae2a0c95d8704e + uses: peter-evans/create-pull-request@9153d834b60caba6d51c9b9510b087acf9f33f83 with: branch: create-whatsnew-pull-request/patch title: "What's new article" diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 8169039d95259..4ed3bce656a93 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -1154,8 +1154,7 @@ }, { "source_path_from_root": "/docs/core/testing/unit-testing-mstest-runner-runsettings.md", - "redirect_url": "/dotnet/core/testing/unit-testing-platform-runsettings", - "redirect_document_id": true + "redirect_url": "/dotnet/core/testing/unit-testing-platform-extensions-vstest-bridge#runsettings-support" }, { "source_path_from_root": "/docs/core/testing/unit-testing-mstest-runner-telemetry.md", diff --git a/.openpublishing.redirection.csharp.json b/.openpublishing.redirection.csharp.json index bfdcf20d917d3..4f83cd72893a6 100644 --- a/.openpublishing.redirection.csharp.json +++ b/.openpublishing.redirection.csharp.json @@ -1348,6 +1348,10 @@ "source_path_from_root": "/docs/csharp/linq/perform-a-subquery-on-a-grouping-operation.md", "redirect_url": "/dotnet/csharp/linq/standard-query-operators/grouping-data" }, + { + "source_path_from_root": "/docs/csharp/linq/linq-to-objects.md", + "redirect_url": "/dotnet/csharp/linq/introduction-to-linq-queries" + }, { "source_path_from_root": "/docs/csharp/linq/perform-grouped-joins.md", "redirect_url": "/dotnet/csharp/linq/standard-query-operators/join-operations" @@ -1372,6 +1376,30 @@ "source_path_from_root": "/docs/csharp/linq/query-expression-basics.md", "redirect_url": "/dotnet/csharp/linq/get-started/query-expression-basics" }, + { + "source_path_from_root": "/docs/csharp/linq/query-a-collection-of-objects.md", + "redirect_url": "/dotnet/csharp/linq/get-started/introduction-to-linq-queries" + }, + { + "source_path_from_root": "/docs/csharp/linq/return-a-query-from-a-method.md", + "redirect_url": "/dotnet/csharp/linq/get-started/features-that-support-linq#expressions-as-data" + }, + { + "source_path_from_root": "/docs/csharp/linq/dynamically-specify-predicate-filters-at-runtime.md", + "redirect_url": "/dotnet/csharp/linq/get-started/write-linq-queries" + }, + { + "source_path_from_root": "/docs/csharp/linq/handle-null-values-in-query-expressions.md", + "redirect_url": "/dotnet/csharp/linq/get-started/write-linq-queries" + }, + { + "source_path_from_root": "/docs/csharp/linq/handle-exceptions-in-query-expressions.md", + "redirect_url": "/dotnet/csharp/linq/get-started/write-linq-queries" + }, + { + "source_path_from_root": "/docs/csharp/linq/store-the-results-of-a-query-in-memory.md", + "redirect_url": "/dotnet/csharp/linq/get-started/introduction-to-linq-queries" + }, { "source_path_from_root": "/docs/csharp/linq/write-linq-queries.md", "redirect_url": "/dotnet/csharp/linq/get-started/write-linq-queries" @@ -1965,7 +1993,7 @@ }, { "source_path_from_root": "/docs/csharp/programming-guide/concepts/expression-trees/debugview-syntax.md", - "redirect_url": "/dotnet/csharp/programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries" + "redirect_url": "/dotnet/csharp/linq/how-to-build-dynamic-queries" }, { "source_path_from_root": "/docs/csharp/programming-guide/concepts/expression-trees/how-to-use-expression-trees-to-build-dynamic-queries.md", @@ -2004,6 +2032,70 @@ "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/classification-of-standard-query-operators-by-manner-of-execution.md", "redirect_url": "/dotnet/csharp/linq/query-a-collection-of-objects" }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-join-content-from-dissimilar-files-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-strings" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-strings" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-strings" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-strings" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-combine-linq-queries-with-regular-expressions.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-strings" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-collections" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-combine-and-compare-string-collections-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-collections" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-collections" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md", + "redirect_url": "/dotnet/csharp/linq/how-to-query-collections" + }, + { + "source_path_from_root": "/docs/csharp/linq/group-results-by-contiguous-keys.md", + "redirect_url": "/dotnet/csharp/linq/how-to-extend-linq" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md", + "redirect_url": "/dotnet/csharp/linq/how-to-build-dynamic-queries" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md", + "redirect_url": "/dotnet/csharp/linq/how-to-extend-linq" + }, { "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/query-expression-syntax-for-standard-query-operators.md", "redirect_url": "/dotnet/csharp/linq/standard-query-operators/" @@ -2945,7 +3037,46 @@ { "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/visual-studio-ide-and-tools-support-for-linq.md", "redirect_url": "/dotnet/csharp/linq/" - + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/walkthrough-writing-queries-linq.md", + "redirect_url": "/dotnet/csharp/linq/get-started/walkthrough-writing-queries-linq" + }, + { + "source_path_from_root": "/docs/csharp/linq/walkthrough-writing-queries-linq.md", + "redirect_url": "/dotnet/csharp/linq/get-started/walkthrough-writing-queries-linq" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/linq-and-file-directories.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-for-files-with-a-specified-attribute-or-name.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders-linq.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-compare-the-contents-of-two-folders-linq.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree-linq.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-for-duplicate-files-in-a-directory-tree-linq.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" + }, + { + "source_path_from_root": "/docs/csharp/programming-guide/concepts/linq/how-to-query-the-contents-of-files-in-a-folder-lin.md", + "redirect_url": "/dotnet/csharp/linq//how-to-query-files-and-directories" }, { "source_path_from_root": "/docs/csharp/programming-guide/concepts/object-oriented-programming.md", diff --git a/docs/ai/azure-ai-for-dotnet-developers.md b/docs/ai/azure-ai-for-dotnet-developers.md index 5430ffcb7ac15..e6c9889819d7b 100644 --- a/docs/ai/azure-ai-for-dotnet-developers.md +++ b/docs/ai/azure-ai-for-dotnet-developers.md @@ -10,4 +10,4 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai This article provides documentation, samples, and other resources for learning how to develop applications that use Azure OpenAI Service and other Azure AI Services. -[!INCLUDE [include-file-from-azure-dev-docs-pr](~/azure-dev-docs-pr/articles/intro/includes/azure-ai-for-developers-dotnet.md)] +[!INCLUDE [include-file-from-azure-dev-docs-pr](~/azure-dev-docs-pr/articles/ai/includes/azure-ai-for-developers-dotnet.md)] diff --git a/docs/ai/get-started-app-chat-scaling-with-azure-container-apps.md b/docs/ai/get-started-app-chat-scaling-with-azure-container-apps.md index 2babbad8cd0d2..620e5e48c7b0e 100644 --- a/docs/ai/get-started-app-chat-scaling-with-azure-container-apps.md +++ b/docs/ai/get-started-app-chat-scaling-with-azure-container-apps.md @@ -9,7 +9,7 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai # Scale Azure OpenAI for .NET chat using RAG with Azure Container Apps -[!INCLUDE [aca-load-balancer-intro](~/azure-dev-docs-pr/articles/intro/includes//scaling-load-balancer-introduction-azure-container-apps.md)] +[!INCLUDE [aca-load-balancer-intro](~/azure-dev-docs-pr/articles/ai/includes//scaling-load-balancer-introduction-azure-container-apps.md)] ## Prerequisites @@ -32,15 +32,15 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai --- -[!INCLUDE [scaling-load-balancer-aca-procedure.md](~/azure-dev-docs-pr/articles/intro/includes//scaling-load-balancer-procedure-azure-container-apps.md)] +[!INCLUDE [scaling-load-balancer-aca-procedure.md](~/azure-dev-docs-pr/articles/ai/includes//scaling-load-balancer-procedure-azure-container-apps.md)] -[!INCLUDE [redeployment-procedure](~/azure-dev-docs-pr/articles/intro/includes//redeploy-procedure-chat.md)] +[!INCLUDE [redeployment-procedure](~/azure-dev-docs-pr/articles/ai/includes//redeploy-procedure-chat.md)] -[!INCLUDE [logs](~/azure-dev-docs-pr/articles/intro/includes//scaling-load-balancer-logs-azure-container-apps.md)] +[!INCLUDE [logs](~/azure-dev-docs-pr/articles/ai/includes//scaling-load-balancer-logs-azure-container-apps.md)] -[!INCLUDE [capacity.md](~/azure-dev-docs-pr/articles/intro/includes//scaling-load-balancer-capacity.md)] +[!INCLUDE [capacity.md](~/azure-dev-docs-pr/articles/ai/includes//scaling-load-balancer-capacity.md)] -[!INCLUDE [aca-cleanup](~/azure-dev-docs-pr/articles/intro/includes//scaling-load-balancer-cleanup-azure-container-apps.md)] +[!INCLUDE [aca-cleanup](~/azure-dev-docs-pr/articles/ai/includes//scaling-load-balancer-cleanup-azure-container-apps.md)] ## Sample code diff --git a/docs/architecture/maui/preface.md b/docs/architecture/maui/preface.md index f86e60319ab31..e3b2e783f9f77 100644 --- a/docs/architecture/maui/preface.md +++ b/docs/architecture/maui/preface.md @@ -14,7 +14,7 @@ This eBook provides guidance on building cross-platform enterprise apps using .N The guide provides architectural guidance for developing adaptable, maintainable, and testable .NET MAUI enterprise apps. Guidance is provided on how to implement MVVM, dependency injection, navigation, validation, and configuration management, while maintaining loose coupling. In addition, there's also guidance on performing authentication and authorization with IdentityServer, accessing data from containerized microservices, and unit testing. -The guide comes with source code for the [eShopOnContainers multi-platform app](https://github.com/dotnet-architecture/eShopOnContainers/tree/master/src/Mobile), and source code for the [eShopOnContainers reference app](https://github.com/dotnet-architecture/eShopOnContainers). The eShopOnContainers multi-platform app is a cross-platform enterprise app developed using .NET MAUI, which connects to a series of containerized microservices known as the eShopOnContainers reference app. However, the eShopOnContainers multi-platform app can be configured to consume data from mock services for those who wish to avoid deploying the containerized microservices. +The guide comes with source code for the [eShopOnContainers multi-platform app](https://github.com/dotnet-architecture/eShopOnContainers/tree/main/src/Mobile), and source code for the [eShopOnContainers reference app](https://github.com/dotnet-architecture/eShopOnContainers). The eShopOnContainers multi-platform app is a cross-platform enterprise app developed using .NET MAUI, which connects to a series of containerized microservices known as the eShopOnContainers reference app. However, the eShopOnContainers multi-platform app can be configured to consume data from mock services for those who wish to avoid deploying the containerized microservices. ## What's left out of this guide's scope diff --git a/docs/architecture/microservices/multi-container-microservice-net-applications/data-driven-crud-microservice.md b/docs/architecture/microservices/multi-container-microservice-net-applications/data-driven-crud-microservice.md index 0474f3c2a5f00..e3fcd727dfccb 100644 --- a/docs/architecture/microservices/multi-container-microservice-net-applications/data-driven-crud-microservice.md +++ b/docs/architecture/microservices/multi-container-microservice-net-applications/data-driven-crud-microservice.md @@ -361,7 +361,6 @@ Currently, Swashbuckle consists of five internal NuGet packages under the high-l After you have installed these NuGet packages in your Web API project, you need to configure Swagger in the _Program.cs_ class, as in the following **simplified** code: ```csharp - // Add framework services. builder.Services.AddSwaggerGen(options => @@ -377,12 +376,16 @@ builder.Services.AddSwaggerGen(options => // Other startup code... -app.UseSwagger() - .UseSwaggerUI(c => +app.UseSwagger(); + +if (app.Environment.IsDevelopment()) +{ + app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); }); - ``` +} +``` Once this is done, you can start your application and browse the following Swagger JSON and UI endpoints using URLs like these: diff --git a/docs/architecture/microservices/secure-net-microservices-web-applications/index.md b/docs/architecture/microservices/secure-net-microservices-web-applications/index.md index 12715b6934d38..0227feed3b967 100644 --- a/docs/architecture/microservices/secure-net-microservices-web-applications/index.md +++ b/docs/architecture/microservices/secure-net-microservices-web-applications/index.md @@ -35,7 +35,7 @@ The primary mechanism in ASP.NET Core for identifying an application's users is > [!TIP] > ASP.NET Core 2.1 and later provides [ASP.NET Core Identity](/aspnet/core/security/authentication/identity) as a [Razor Class Library](/aspnet/core/razor-pages/ui-class), so you won't see much of the necessary code in your project, as was the case for previous versions. For details on how to customize the Identity code to suit your needs, see [Scaffold Identity in ASP.NET Core projects](/aspnet/core/security/authentication/scaffold-identity). -The following code is taken from the ASP.NET Core Web Application MVC 3.1 project template with individual user account authentication selected. It shows how to configure ASP.NET Core Identity using Entity Framework Core in the _Program.cs_ file. +The following code is taken from the ASP.NET Core Web Application MVC project template with individual user account authentication selected. It shows how to configure ASP.NET Core Identity using Entity Framework Core in the _Program.cs_ file. ```csharp //... diff --git a/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md b/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md index 0ea0b49e7a6d2..7180b3c0e144e 100644 --- a/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md +++ b/docs/architecture/modern-web-apps-azure/develop-asp-net-core-mvc-apps.md @@ -532,7 +532,7 @@ In web-based authentication, there are typically up to five actions that may be There are a number of common techniques for performing authentication in web applications. These are referred to as schemes. A given scheme will define actions for some or all of the above options. Some schemes only support a subset of actions, and may require a separate scheme to perform those it does not support. For example, the OpenId-Connect (OIDC) scheme doesn't support Sign-in or Sign-out, but is commonly configured to use Cookie authentication for this persistence. -In your ASP.NET Core application, you can configure a `DefaultAuthenticateScheme` as well as optional specific schemes for each of the actions described above. For example, `DefaultChallengeScheme`, `DefaultForbidScheme`, etc. Calling [`AddIdentity`](https://github.com/dotnet/aspnetcore/blob/release/3.1/src/Identity/Core/src/IdentityServiceCollectionExtensions.cs#L38-L102) configures a number of aspects of the application and adds many required services. It also includes this call to configure the authentication scheme: +In your ASP.NET Core application, you can configure a `DefaultAuthenticateScheme` as well as optional specific schemes for each of the actions described above. For example, `DefaultChallengeScheme` and `DefaultForbidScheme`. Calling configures a number of aspects of the application and adds many required services. It also includes this call to configure the authentication scheme: ```csharp builder.Services.AddAuthentication(options => diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index e13249f2c9683..56b35638b895e 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -1,7 +1,7 @@ | Name | Package | Docs | Source | | ---- | ------- | ---- | ------ | | Anomaly Detector | NuGet [3.0.0-preview.7](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.7) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [3.0.0-preview.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.7/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | -| App Configuration | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.4.0) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.4.0/sdk/appconfiguration/Azure.Data.AppConfiguration/) | +| App Configuration | NuGet [1.4.1](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.4.1) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.4.1/sdk/appconfiguration/Azure.Data.AppConfiguration/) | | App Configuration Provider | NuGet [7.0.0](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.AzureAppConfiguration/7.0.0)
NuGet [7.1.0-preview](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.AzureAppConfiguration/7.1.0-preview) | | GitHub [7.0.0](https://github.com/Azure/AppConfiguration-DotnetProvider) | | Attestation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0/sdk/attestation/Azure.Security.Attestation/) | | Azure AI Search | NuGet [11.5.1](https://www.nuget.org/packages/Azure.Search.Documents/11.5.1)
NuGet [11.6.0-beta.3](https://www.nuget.org/packages/Azure.Search.Documents/11.6.0-beta.3) | [docs](/dotnet/api/overview/azure/Search.Documents-readme) | GitHub [11.5.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.5.1/sdk/search/Azure.Search.Documents/)
GitHub [11.6.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.6.0-beta.3/sdk/search/Azure.Search.Documents/) | @@ -9,23 +9,25 @@ | Azure Remote Rendering | NuGet [1.1.0](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.1.0) | [docs](/dotnet/api/overview/azure/MixedReality.RemoteRendering-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.1.0/sdk/remoterendering/Azure.MixedReality.RemoteRendering/) | | Code Transparency | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Security.CodeTransparency/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Security.CodeTransparency-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.CodeTransparency_1.0.0-beta.2/sdk/confidentialledger/Azure.Security.CodeTransparency/) | | Communication Call Automation | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.1.0) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.1.0/sdk/communication/Azure.Communication.CallAutomation/) | -| Communication Chat | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Communication.Chat/1.2.0) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.2.0/sdk/communication/Azure.Communication.Chat/) | +| Communication Chat | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.0) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.0/sdk/communication/Azure.Communication.Chat/) | | Communication Common | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Common/1.3.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Common/2.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.3.0/sdk/communication/Azure.Communication.Common/)
GitHub [2.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_2.0.0-beta.1/sdk/communication/Azure.Communication.Common/) | | Communication Email | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Email/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Email-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.0.1/sdk/communication/Azure.Communication.Email/) | | Communication Identity | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.3.1/sdk/communication/Azure.Communication.Identity/) | | Communication JobRouter | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Communication.JobRouter/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.JobRouter/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.JobRouter-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.JobRouter_1.0.0/sdk/communication/Azure.Communication.JobRouter/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.JobRouter_1.1.0-beta.1/sdk/communication/Azure.Communication.JobRouter/) | | Communication Messages | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Communication.Messages/1.0.0) | [docs](/dotnet/api/overview/azure/Communication.Messages-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Messages_1.0.0/sdk/communication/Azure.Communication.Messages/) | | Communication Phone Numbers | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.1.0)
NuGet [1.3.0-beta.5](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.3.0-beta.5) | [docs](/dotnet/api/overview/azure/Communication.PhoneNumbers-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.1.0/sdk/communication/Azure.Communication.PhoneNumbers/)
GitHub [1.3.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.3.0-beta.5/sdk/communication/Azure.Communication.PhoneNumbers/) | -| Communication Rooms | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Communication.Rooms/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Rooms/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Rooms-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Rooms_1.0.0/sdk/communication/Azure.Communication.Rooms/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Rooms_1.1.0-beta.1/sdk/communication/Azure.Communication.Rooms/) | -| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/) | +| Communication Rooms | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Communication.Rooms/1.1.0) | [docs](/dotnet/api/overview/azure/Communication.Rooms-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Rooms_1.1.0/sdk/communication/Azure.Communication.Rooms/) | +| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.1.0-beta.1/sdk/communication/Azure.Communication.Sms/) | | Confidential Ledger | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Security.ConfidentialLedger/1.3.0) | [docs](/dotnet/api/overview/azure/Security.ConfidentialLedger-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.ConfidentialLedger_1.3.0/sdk/confidentialledger/Azure.Security.ConfidentialLedger/) | | Container Registry | NuGet [1.1.1](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.1.1)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Containers.ContainerRegistry-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.1.1/sdk/containerregistry/Azure.Containers.ContainerRegistry/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.2.0-beta.1/sdk/containerregistry/Azure.Containers.ContainerRegistry/) | | Content Safety | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.ContentSafety/1.0.0) | [docs](/dotnet/api/overview/azure/AI.ContentSafety-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.ContentSafety_1.0.0/sdk/contentsafety/Azure.AI.ContentSafety/) | | Conversational Language Understanding | NuGet [1.1.0](https://www.nuget.org/packages/Azure.AI.Language.Conversations/1.1.0) | [docs](/dotnet/api/overview/azure/AI.Language.Conversations-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Language.Conversations_1.1.0/sdk/cognitivelanguage/Azure.AI.Language.Conversations/) | | Core - Client - AMQP | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.3.0) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.3.0/sdk/core/Azure.Core.Amqp/) | -| Core - Client - Core | NuGet [1.38.0](https://www.nuget.org/packages/Azure.Core/1.38.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.38.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.38.0/sdk/core/Azure.Core/) | +| Core - Client - Core | NuGet [1.39.0](https://www.nuget.org/packages/Azure.Core/1.39.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.39.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.39.0/sdk/core/Azure.Core/) | | Core Newtonsoft Json | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.NewtonsoftJson/2.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.NewtonsoftJson-readme) | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.NewtonsoftJson_2.0.0/sdk/core/Microsoft.Azure.Core.NewtonsoftJson/) | | Data Movement | NuGet [12.0.0-beta.4](https://www.nuget.org/packages/Azure.Storage.DataMovement/12.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.DataMovement-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.DataMovement_12.0.0-beta.4/sdk/storage/Azure.Storage.DataMovement/) | +| Data Movement - Blobs | NuGet [12.0.0-beta.4](https://www.nuget.org/packages/Azure.Storage.DataMovement.Blobs/12.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.DataMovement.Blobs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.DataMovement.Blobs_12.0.0-beta.4/sdk/storage/Azure.Storage.DataMovement.Blobs/) | +| Data Movement - Files Shares | NuGet [12.0.0-beta.1](https://www.nuget.org/packages/Azure.Storage.DataMovement.Files.Shares/12.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.DataMovement.Files.Shares-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.DataMovement.Files.Shares_12.0.0-beta.1/sdk/storage/Azure.Storage.DataMovement.Files.Shares/) | | Defender EASM | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Defender.Easm/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Defender.Easm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Defender.Easm_1.0.0-beta.1/sdk/easm/Azure.Analytics.Defender.Easm/) | | Dev Center | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Developer.DevCenter/1.0.0) | [docs](/dotnet/api/overview/azure/Developer.DevCenter-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.DevCenter_1.0.0/sdk/devcenter/Azure.Developer.DevCenter/) | | Device Update | NuGet [1.0.0](https://www.nuget.org/packages/Azure.IoT.DeviceUpdate/1.0.0) | [docs](/dotnet/api/overview/azure/IoT.DeviceUpdate-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.DeviceUpdate_1.0.0/sdk/deviceupdate/Azure.IoT.DeviceUpdate/) | @@ -33,7 +35,7 @@ | Document Intelligence | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.DocumentIntelligence/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.DocumentIntelligence-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.DocumentIntelligence_1.0.0-beta.2/sdk/documentintelligence/Azure.AI.DocumentIntelligence/) | | Document Translation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0/sdk/translation/Azure.AI.Translation.Document/) | | Event Grid | NuGet [4.24.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.24.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.24.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.24.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | -| Event Grid Namespaces | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventGrid.Namespaces/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid.Namespaces_1.0.0-beta.1/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/) | +| Event Grid Namespaces | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventGrid.Namespaces/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid.Namespaces-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid.Namespaces_1.0.0-beta.1/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/) | | Event Hubs | NuGet [5.11.2](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.11.2) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.11.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.11.2/sdk/eventhub/Azure.Messaging.EventHubs/) | | Event Hubs - Event Processor | NuGet [5.11.2](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.11.2) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.11.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.11.2/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | | FarmBeats | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Verticals.AgriFood.Farming/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Verticals.AgriFood.Farming-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Verticals.AgriFood.Farming_1.0.0-beta.2/sdk/agrifood/Azure.Verticals.AgriFood.Farming/) | @@ -41,7 +43,7 @@ | Health Insights Cancer Profiling | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.CancerProfiling/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.CancerProfiling-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.CancerProfiling_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.CancerProfiling/) | | Health Insights Clinical Matching | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.ClinicalMatching/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.ClinicalMatching-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.ClinicalMatching_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.ClinicalMatching/) | | Health Insights Radiology Insights | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.RadiologyInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.RadiologyInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.RadiologyInsights_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.RadiologyInsights/) | -| Identity | NuGet [1.11.0](https://www.nuget.org/packages/Azure.Identity/1.11.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.11.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.11.0/sdk/identity/Azure.Identity/) | +| Identity | NuGet [1.11.2](https://www.nuget.org/packages/Azure.Identity/1.11.2)
NuGet [1.12.0-beta.1](https://www.nuget.org/packages/Azure.Identity/1.12.0-beta.1) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.11.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.11.2/sdk/identity/Azure.Identity/)
GitHub [1.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.12.0-beta.1/sdk/identity/Azure.Identity/) | | Identity Broker | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Identity.Broker/1.1.0) | [docs](/dotnet/api/overview/azure/Identity.Broker-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity.Broker_1.1.0/sdk/identity/Azure.Identity.Broker/) | | Image Analysis | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Vision.ImageAnalysis/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Vision.ImageAnalysis-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/vision/Azure.AI.Vision.ImageAnalysis) | | Key Vault - Administration | NuGet [4.4.0](https://www.nuget.org/packages/Azure.Security.KeyVault.Administration/4.4.0) | [docs](/dotnet/api/overview/azure/Security.KeyVault.Administration-readme) | GitHub [4.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.KeyVault.Administration_4.4.0/sdk/keyvault/Azure.Security.KeyVault.Administration/) | @@ -56,13 +58,13 @@ | Maps Search | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Maps.Search/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Maps.Search-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Maps.Search_1.0.0-beta.4/sdk/maps/Azure.Maps.Search/) | | Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge) | | Metrics Advisor | NuGet [1.1.0](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.1.0) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.1.0/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | -| Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents_1.0.0-beta.6/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/) | +| Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents | NuGet [1.0.0-beta.7](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/1.0.0-beta.7) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents_1.0.0-beta.7/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/) | | Mixed Reality Authentication | NuGet [1.2.0](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.2.0) | [docs](/dotnet/api/overview/azure/MixedReality.Authentication-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.2.0/sdk/mixedreality/Azure.MixedReality.Authentication/) | | Monitor Ingestion | NuGet [1.1.2](https://www.nuget.org/packages/Azure.Monitor.Ingestion/1.1.2) | [docs](/dotnet/api/overview/azure/Monitor.Ingestion-readme) | GitHub [1.1.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.Ingestion_1.1.2/sdk/monitor/Azure.Monitor.Ingestion/) | | Monitor Query | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Monitor.Query/1.3.1) | [docs](/dotnet/api/overview/azure/Monitor.Query-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.Query_1.3.1/sdk/monitor/Azure.Monitor.Query/) | | OpenAI Assistants | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.OpenAI.Assistants/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.OpenAI.Assistants-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI.Assistants_1.0.0-beta.3/sdk/openai/Azure.AI.OpenAI.Assistants/) | | OpenAI Inference | NuGet [1.0.0-beta.16](https://www.nuget.org/packages/Azure.AI.OpenAI/1.0.0-beta.16) | [docs](/dotnet/api/overview/azure/AI.OpenAI-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.16](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI_1.0.0-beta.16/sdk/openai/Azure.AI.OpenAI/) | -| OpenTelemetry AspNetCore | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.1.0)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.AspNetCore-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.1.0/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.2.0-beta.2/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/) | +| OpenTelemetry AspNetCore | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.1.0)
NuGet [1.2.0-beta.3](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.2.0-beta.3) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.AspNetCore-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.1.0/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/)
GitHub [1.2.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.2.0-beta.3/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/) | | OpenTelemetry Exporter | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.2.0)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.2.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.3.0-beta.1/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | | OpenTelemetry LiveMetrics | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.LiveMetrics/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.LiveMetrics-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.LiveMetrics_1.0.0-beta.3/sdk/monitor/Azure.Monitor.OpenTelemetry.LiveMetrics/) | | Personalizer | NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Personalizer/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Personalizer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Personalizer_2.0.0-beta.2/sdk/personalizer/Azure.AI.Personalizer/) | @@ -76,12 +78,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.1](https://www.nuget.org/packages/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/1.0.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.1/sdk/schemaregistry/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/) | | Service Bus | NuGet [7.17.5](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.17.5) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.17.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.17.5/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Storage - Blobs | NuGet [12.19.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.19.1)
NuGet [12.20.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.20.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.19.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.19.1/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.20.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.20.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs Batch | NuGet [12.16.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.16.1)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.16.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.16.1/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.17.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.42](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.42) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.42](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.42/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Files Data Lake | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.17.1)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.17.1/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.18.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Share | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.17.1)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.17.1/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.18.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Queues | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.17.1)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.17.1/sdk/storage/Azure.Storage.Queues/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.18.0-beta.1/sdk/storage/Azure.Storage.Queues/) | +| Storage - Blobs | NuGet [12.19.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.19.1)
NuGet [12.20.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Blobs/12.20.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.19.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.19.1/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.20.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.20.0-beta.2/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs Batch | NuGet [12.16.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.16.1)
NuGet [12.17.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.17.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.16.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.16.1/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.17.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.17.0-beta.2/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.43](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.43) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.43](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.43/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Files Data Lake | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.17.1)
NuGet [12.18.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.18.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.17.1/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.18.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.18.0-beta.2/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Share | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.17.1)
NuGet [12.18.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.18.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.17.1/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.18.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.18.0-beta.2/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Queues | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.17.1)
NuGet [12.18.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Queues/12.18.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.17.1/sdk/storage/Azure.Storage.Queues/)
GitHub [12.18.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.18.0-beta.2/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.19](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.19) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.19](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.19/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/) | @@ -93,27 +95,27 @@ | Text Translation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Translation.Text/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Translation.Text-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Text_1.0.0-beta.1/sdk/translation/Azure.AI.Translation.Text/) | | unknown | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.CallingServer/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.CallingServer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallingServer_1.0.0-beta.3/sdk/communication/Azure.Communication.CallingServer/) | | unknown | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Expressions.DataFactory/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Expressions.DataFactory-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Expressions.DataFactory_1.0.0/sdk/core/Azure.Core.Expressions.DataFactory/) | -| unknown | NuGet [1.0.0-preview.5](https://www.nuget.org/packages/Azure.IoT.ModelsRepository/1.0.0-preview.5) | [docs](/dotnet/api/overview/azure/IoT.ModelsRepository-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.ModelsRepository_1.0.0-preview.5/sdk/modelsrepository/Azure.IoT.ModelsRepository/) | +| unknown | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.IoT.ModelsRepository/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/IoT.ModelsRepository-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.ModelsRepository_1.0.0-preview.6/sdk/modelsrepository/Azure.IoT.ModelsRepository/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.IoT.TimeSeriesInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/IoT.TimeSeriesInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.TimeSeriesInsights_1.0.0-beta.1/sdk/timeseriesinsights/Azure.IoT.TimeSeriesInsights/) | | unknown | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Quantum.Jobs/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Quantum.Jobs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Quantum.Jobs_1.0.0-beta.3/sdk/quantum/Azure.Quantum.Jobs/) | | Video Analyzer Edge | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.Media.VideoAnalyzer.Edge/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/Media.VideoAnalyzer.Edge-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.VideoAnalyzer.Edge_1.0.0-beta.6/sdk/videoanalyzer/Azure.Media.VideoAnalyzer.Edge/) | | Vision Common | NuGet [0.15.1-beta.1](https://www.nuget.org/packages/Azure.AI.Vision.Common/0.15.1-beta.1) | | GitHub [0.15.1-beta.1](https://msasg.visualstudio.com/Skyman/_git/Carbon) | | Web PubSub | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub/1.3.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub_1.3.0/sdk/webpubsub/Azure.Messaging.WebPubSub/) | | Web PubSub Client | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub.Client/1.0.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub.Client-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub.Client_1.0.0/sdk/webpubsub/Azure.Messaging.WebPubSub.Client/) | -| Azure client library integration for ASP.NET Core | NuGet [1.7.2](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.2) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.2/sdk/extensions/Microsoft.Extensions.Azure/) | -| Blob Storage Key Store for .NET Data Protection | NuGet [1.3.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.3.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.3.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.3.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | +| Azure client library integration for ASP.NET Core | NuGet [1.7.3](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.3) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.3](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.3/sdk/extensions/Microsoft.Extensions.Azure/) | +| Blob Storage Key Store for .NET Data Protection | NuGet [1.3.4](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.3.4) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.3.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.3.4/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | | CloudNative CloudEvents with Event Grid | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/1.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents_1.0.0/sdk/eventgrid/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/) | | Core - Client - Spatial | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.Spatial-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.1.0/sdk/core/Microsoft.Azure.Core.Spatial/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.2.0-beta.1/sdk/core/Microsoft.Azure.Core.Spatial/) | | Core - Client - Spatial Newtonsoft Json | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial.NewtonsoftJson/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial.NewtonsoftJson/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.Spatial.NewtonsoftJson-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial.NewtonsoftJson_1.0.0/sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial.NewtonsoftJson_1.1.0-beta.1/sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/) | -| Functions extension for Azure Tables | NuGet [1.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Tables/1.2.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Tables-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Tables_1.2.1/sdk/tables/Microsoft.Azure.WebJobs.Extensions.Tables/) | +| Functions extension for Azure Tables | NuGet [1.3.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Tables/1.3.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Tables-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Tables_1.3.1/sdk/tables/Microsoft.Azure.WebJobs.Extensions.Tables/) | | Key Encryptor for .NET Data Protection | NuGet [1.2.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.2.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.2.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.2.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | | Secrets Configuration Provider for .NET | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.3.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.3.1/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| Storage - Common | NuGet [12.18.1](https://www.nuget.org/packages/Azure.Storage.Common/12.18.1)
NuGet [12.19.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.19.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.18.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.18.1/sdk/storage/Azure.Storage.Common/)
GitHub [12.19.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.19.0-beta.1/sdk/storage/Azure.Storage.Common/) | -| WebJobs Extensions - Event Grid | NuGet [3.3.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.3.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventGrid-readme) | GitHub [3.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventGrid_3.3.1/sdk/eventgrid/Microsoft.Azure.WebJobs.Extensions.EventGrid/) | -| WebJobs Extensions - Event Hubs | NuGet [6.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/6.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventHubs-readme) | GitHub [6.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventHubs_6.3.0/sdk/eventhub/Microsoft.Azure.WebJobs.Extensions.EventHubs/) | -| WebJobs Extensions - Service Bus | NuGet [5.14.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.14.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.ServiceBus-readme) | GitHub [5.14.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.14.0/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/) | +| Storage - Common | NuGet [12.18.1](https://www.nuget.org/packages/Azure.Storage.Common/12.18.1)
NuGet [12.19.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Common/12.19.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.18.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.18.1/sdk/storage/Azure.Storage.Common/)
GitHub [12.19.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.19.0-beta.2/sdk/storage/Azure.Storage.Common/) | +| WebJobs Extensions - Event Grid | NuGet [3.4.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.4.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventGrid-readme) | GitHub [3.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventGrid_3.4.1/sdk/eventgrid/Microsoft.Azure.WebJobs.Extensions.EventGrid/) | +| WebJobs Extensions - Event Hubs | NuGet [6.3.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/6.3.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventHubs-readme) | GitHub [6.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventHubs_6.3.1/sdk/eventhub/Microsoft.Azure.WebJobs.Extensions.EventHubs/) | +| WebJobs Extensions - Service Bus | NuGet [5.15.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.15.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.ServiceBus-readme) | GitHub [5.15.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.15.1/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/) | | WebJobs Extensions - SignalR Service | NuGet [1.13.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SignalRService/1.13.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.SignalRService-readme) | GitHub [1.13.0](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/SignalRServiceExtension) | -| WebJobs Extensions - Storage | NuGet [5.2.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/5.2.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage-readme) | GitHub [5.2.2](https://github.com/Azure/azure-webjobs-sdk/tree/master/src/Microsoft.Azure.WebJobs.Extensions.Storage) | +| WebJobs Extensions - Storage | NuGet [5.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/5.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage-readme) | GitHub [5.3.0](https://github.com/Azure/azure-webjobs-sdk/tree/master/src/Microsoft.Azure.WebJobs.Extensions.Storage) | | WebJobs Extensions - Web PubSub | NuGet [1.7.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSub/1.7.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.WebPubSub-readme) | GitHub [1.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.WebPubSub_1.7.0/sdk/webpubsub/Microsoft.Azure.WebJobs.Extensions.WebPubSub/) | | Provisioning | NuGet [0.2.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning/0.2.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_0.2.0-beta.2/sdk/provisioning/Azure.Provisioning/) | | Provisioning - App Configuration | NuGet [0.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/0.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_0.1.0-beta.1/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | @@ -136,18 +138,18 @@ | Resource Management - Alerts Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.AlertsManagement/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AlertsManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AlertsManagement_1.1.0/sdk/alertsmanagement/Azure.ResourceManager.AlertsManagement/) | | Resource Management - Analysis | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Analysis/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Analysis-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Analysis_1.1.0/sdk/analysisservices/Azure.ResourceManager.Analysis/) | | Resource Management - API Center | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ApiCenter/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ApiCenter-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiCenter_1.0.0-beta.2/sdk/apicenter/Azure.ResourceManager.ApiCenter/) | -| Resource Management - API Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ApiManagement/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ApiManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiManagement_1.1.0/sdk/apimanagement/Azure.ResourceManager.ApiManagement/) | +| Resource Management - API Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ApiManagement/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ApiManagement/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ApiManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiManagement_1.1.0/sdk/apimanagement/Azure.ResourceManager.ApiManagement/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiManagement_1.2.0-beta.1/sdk/apimanagement/Azure.ResourceManager.ApiManagement/) | | Resource Management - App Compliance Automation | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.AppComplianceAutomation/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.AppComplianceAutomation-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppComplianceAutomation_1.0.0-beta.4/sdk/appcomplianceautomation/Azure.ResourceManager.AppComplianceAutomation/) | | Resource Management - App Configuration | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.3.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.3.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | | Resource Management - App Platform | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.AppPlatform/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AppPlatform-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppPlatform_1.1.0/sdk/appplatform/Azure.ResourceManager.AppPlatform/) | -| Resource Management - App Service | NuGet [1.0.2](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.0.2)
NuGet [1.1.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.1.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.AppService-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.0.2/sdk/websites/Azure.ResourceManager.AppService/)
GitHub [1.1.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.1.0-beta.4/sdk/websites/Azure.ResourceManager.AppService/) | +| Resource Management - App Service | NuGet [1.0.2](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.0.2)
NuGet [1.1.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.1.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.AppService-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.0.2/sdk/websites/Azure.ResourceManager.AppService/)
GitHub [1.1.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.1.0-beta.5/sdk/websites/Azure.ResourceManager.AppService/) | | Resource Management - Application Insights | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.ApplicationInsights/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ApplicationInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApplicationInsights_1.0.0-beta.5/sdk/applicationinsights/Azure.ResourceManager.ApplicationInsights/) | | Resource Management - Arc ScVmm | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.ArcScVmm/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.ArcScVmm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArcScVmm_1.0.0-beta.4/sdk/arc-scvmm/Azure.ResourceManager.ArcScVmm/) | | Resource Management - Attestation | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.Attestation/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.Attestation-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Attestation_1.0.0-beta.4/sdk/attestation/Azure.ResourceManager.Attestation/) | | Resource Management - Authorization | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Authorization/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Authorization-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Authorization_1.1.1/sdk/authorization/Azure.ResourceManager.Authorization/) | | Resource Management - Automanage | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Automanage/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Automanage-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automanage_1.1.0/sdk/automanage/Azure.ResourceManager.Automanage/) | | Resource Management - Automation | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Automation/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Automation-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automation_1.1.0/sdk/automation/Azure.ResourceManager.Automation/) | -| Resource Management - Azure AI Search | NuGet [1.2.2](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.2/sdk/search/Azure.ResourceManager.Search/) | +| Resource Management - Azure AI Search | NuGet [1.2.2](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.2)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.2/sdk/search/Azure.ResourceManager.Search/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.3.0-beta.1/sdk/search/Azure.ResourceManager.Search/) | | Resource Management - Azure Stack HCI | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Hci/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Hci/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Hci-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Hci_1.1.0/sdk/azurestackhci/Azure.ResourceManager.Hci/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Hci_1.2.0-beta.1/sdk/azurestackhci/Azure.ResourceManager.Hci/) | | Resource Management - Azure VMware Solution | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Avs/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Avs-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Avs_1.3.0/sdk/avs/Azure.ResourceManager.Avs/) | | Resource Management - Batch | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.Batch/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Batch-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Batch_1.4.0/sdk/batch/Azure.ResourceManager.Batch/) | @@ -280,7 +282,7 @@ | Resource Management - Resource Connector | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ResourceConnector/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceConnector-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceConnector_1.0.0-beta.2/sdk/resourceconnector/Azure.ResourceManager.ResourceConnector/) | | Resource Management - Resource Graph | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ResourceGraph/1.0.1)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ResourceGraph/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceGraph-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceGraph_1.0.1/sdk/resourcegraph/Azure.ResourceManager.ResourceGraph/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceGraph_1.1.0-beta.2/sdk/resourcegraph/Azure.ResourceManager.ResourceGraph/) | | Resource Management - Resource Health | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ResourceHealth/1.0.0)
NuGet [1.1.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.ResourceHealth/1.1.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceHealth-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceHealth_1.0.0/sdk/resourcehealth/Azure.ResourceManager.ResourceHealth/)
GitHub [1.1.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceHealth_1.1.0-beta.3/sdk/resourcehealth/Azure.ResourceManager.ResourceHealth/) | -| Resource Management - Resource Manager | NuGet [1.11.0](https://www.nuget.org/packages/Azure.ResourceManager/1.11.0)
NuGet [1.12.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager/1.12.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager-readme) | GitHub [1.11.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.11.0/sdk/resourcemanager/Azure.ResourceManager/)
GitHub [1.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.12.0-beta.1/sdk/resourcemanager/Azure.ResourceManager/) | +| Resource Management - Resource Manager | NuGet [1.11.1](https://www.nuget.org/packages/Azure.ResourceManager/1.11.1)
NuGet [1.12.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager/1.12.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager-readme) | GitHub [1.11.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.11.1/sdk/resourcemanager/Azure.ResourceManager/)
GitHub [1.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.12.0-beta.1/sdk/resourcemanager/Azure.ResourceManager/) | | Resource Management - Resource Mover | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.ResourceMover/1.1.1)
NuGet [1.1.2-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ResourceMover/1.1.2-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceMover-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceMover_1.1.1/sdk/resourcemover/Azure.ResourceManager.ResourceMover/)
GitHub [1.1.2-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceMover_1.1.2-beta.1/sdk/resourcemover/Azure.ResourceManager.ResourceMover/) | | Resource Management - Resources | NuGet [1.7.1](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.7.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme) | GitHub [1.7.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.7.1/sdk/resources/Azure.ResourceManager.Resources/) | | Resource Management - ScVmm | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.ScVmm/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ScVmm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ScVmm_1.0.0-beta.5/sdk/arc-scvmm/Azure.ResourceManager.ScVmm/) | @@ -310,17 +312,17 @@ | Resource Management - Synapse | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Synapse/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Synapse-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Synapse_1.2.0/sdk/synapse/Azure.ResourceManager.Synapse/) | | Resource Management - Traffic Manager | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.TrafficManager/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.TrafficManager-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.TrafficManager_1.1.1/sdk/trafficmanager/Azure.ResourceManager.TrafficManager/) | | Resource Management - Voice Services | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.VoiceServices/1.0.1) | [docs](/dotnet/api/overview/azure/ResourceManager.VoiceServices-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.VoiceServices_1.0.1/sdk/voiceservices/Azure.ResourceManager.VoiceServices/) | -| Resource Management - Web PubSub | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.WebPubSub/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.WebPubSub-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WebPubSub_1.1.0/sdk/webpubsub/Azure.ResourceManager.WebPubSub/) | +| Resource Management - Web PubSub | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.WebPubSub/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.WebPubSub/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.WebPubSub-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WebPubSub_1.1.0/sdk/webpubsub/Azure.ResourceManager.WebPubSub/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WebPubSub_1.2.0-beta.1/sdk/webpubsub/Azure.ResourceManager.WebPubSub/) | | Resource Management - Workload Monitor | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.WorkloadMonitor/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.WorkloadMonitor-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WorkloadMonitor_1.0.0-beta.4/sdk/workloadmonitor/Azure.ResourceManager.WorkloadMonitor/) | | Resource Management - Workloads | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Workloads/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Workloads/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Workloads-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Workloads_1.1.0/sdk/workloads/Azure.ResourceManager.Workloads/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Workloads_1.2.0-beta.1/sdk/workloads/Azure.ResourceManager.Workloads/) | | Azure.Communication.Administration | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.Administration/1.0.0-beta.3) | | | | Communication Calling Windows Client | NuGet [1.6.0](https://www.nuget.org/packages/Azure.Communication.Calling.WindowsClient/1.6.0) | | | -| Data Movement - Files Shares | NuGet [12.0.0-beta.1](https://www.nuget.org/packages/Azure.Storage.DataMovement.Files.Shares/12.0.0-beta.1) | | | | DotNetty | NuGet [0.7.6](https://www.nuget.org/packages/DotNetty.Common/0.7.6) | | | | HTTP ASPNETCore Analyzers | NuGet [1.0.2](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore.Analyzers/1.0.2) | | | | Item Templates NetCore | NuGet [4.0.2945](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.ItemTemplates.NetCore/4.0.2945) | | | | Item Templates NetFx | NuGet [4.0.2945](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.ItemTemplates.NetFx/4.0.2945) | | | | System Net Client Model | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/System.Net.ClientModel/1.0.0-beta.1) | | | +| Unknown Display Name | NuGet [1.0.0-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.OpenTelemetry/1.0.0-preview1) | | | | Anomaly Detector | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.AnomalyDetector/1.0.0) | | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.AnomalyDetector_1.0.0-preview.1/sdk/cognitiveservices/AnomalyDetector) | | App Service | NuGet [0.2.2-alpha](https://www.nuget.org/packages/Microsoft.Azure.AppService/0.2.2-alpha) | | | | Application Insights | NuGet [0.9.0-preview](https://www.nuget.org/packages/Microsoft.Azure.ApplicationInsights/0.9.0-preview) | | | @@ -343,7 +345,7 @@ | Common | NuGet [2.2.1](https://www.nuget.org/packages/Microsoft.Azure.Common/2.2.1) | | | | Common - Dependencies | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Common.Dependencies/1.0.0) | | | | Computer Vision | NuGet [7.0.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.ComputerVision/7.0.1) | | GitHub [7.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.ComputerVision_6.0.0-preview.1/sdk/cognitiveservices/Vision.ComputerVision) | -| Cosmos DB | NuGet [3.37.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.37.1)
NuGet [3.39.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.39.0-preview.1) | [docs](https://learn.microsoft.com/dotnet/api/overview/azure/cosmosdb) | GitHub [3.37.1](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | +| Cosmos DB | NuGet [3.37.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.37.1)
NuGet [3.40.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.40.0-preview.1) | [docs](https://learn.microsoft.com/dotnet/api/overview/azure/cosmosdb) | GitHub [3.37.1](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/3.12.0/Microsoft.Azure.Cosmos) | | Custom Image Search | NuGet [2.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.BingCustomImageSearch/2.1.0-preview.1) | | GitHub [2.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Search.BingCustomImageSearch_2.1.0-preview.1/sdk/cognitiveservices/Search.BingCustomImageSearch) | | Custom Image Search | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.CustomImageSearch/2.0.0) | | | | Custom Search | NuGet [2.1.0-preview.1](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Search.BingCustomSearch/2.1.0-preview.1) | | GitHub [2.1.0-preview.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Search.BingCustomSearch_2.1.0-preview.1/sdk/cognitiveservices/Search.BingCustomSearch) | @@ -352,7 +354,6 @@ | Custom Vision Training | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.0.0)
NuGet [2.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training/2.1.0-preview) | | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training_2.0.0/sdk/cognitiveservices/Vision.CustomVision.Training) | | Data Lake Analytics | NuGet [1.4.211011](https://www.nuget.org/packages/Microsoft.Azure.DataLake.USQL.SDK/1.4.211011) | | | | Data Movement | NuGet [2.0.4](https://www.nuget.org/packages/Microsoft.Azure.Storage.DataMovement/2.0.4) | | GitHub [2.0.4](https://github.com/Azure/azure-storage-net-data-movement/tree/v1.3.0) | -| Data Movement - Blobs | NuGet [12.0.0-beta.4](https://www.nuget.org/packages/Azure.Storage.DataMovement.Blobs/12.0.0-beta.4) | | | | DCAP | NuGet [1.12.3](https://www.nuget.org/packages/Microsoft.Azure.DCAP/1.12.3) | | GitHub [1.12.3](https://github.com/microsoft/Azure-DCAP-Client/tree/1.6) | | Devices Provisioning Service | NuGet [1.18.1](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Service/1.18.1)
NuGet [1.19.1-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.Provisioning.Service/1.19.1-preview-001) | | | | Digital Twins Service | NuGet [1.0.0-preview-001](https://www.nuget.org/packages/Microsoft.Azure.Devices.DigitalTwin.Service/1.0.0-preview-001) | | | @@ -432,8 +433,8 @@ | Functions extension for Application Insights | NuGet [1.0.0-preview4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ApplicationInsights/1.0.0-preview4) | | | | Functions extension for Azure Mobile Apps | NuGet [3.0.0-beta8](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.MobileApps/3.0.0-beta8) | | GitHub [3.0.0-beta8](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0-beta8/src/WebJobs.Extensions.MobileApps) | | Functions extension for Azure SQL and SQL Server | NuGet [3.0.534](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Sql/3.0.534) | | | -| Functions extension for Blob Storage | NuGet [5.2.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.2.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs-readme) | | -| Functions extension for Cosmos DB | NuGet [4.6.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB/4.6.0) | | GitHub [4.6.0](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/cosmos-v3.0.7/src/WebJobs.Extensions.CosmosDB) | +| Functions extension for Blob Storage | NuGet [5.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs-readme) | | +| Functions extension for Cosmos DB | NuGet [4.6.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.CosmosDB/4.6.1) | | GitHub [4.6.1](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/cosmos-v3.0.7/src/WebJobs.Extensions.CosmosDB) | | Functions extension for DocumentDB | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DocumentDB/1.3.0) | | GitHub [1.3.0](https://github.com/Azure/azure-webjobs-sdk-extensions) | | Functions extension for Durable Task Framework | NuGet [2.13.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask/2.13.0)
NuGet [3.0.0-rc.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask/3.0.0-rc.1) | [docs](https://learn.microsoft.com/dotnet/api/overview/azure/functions) | GitHub [2.13.0](https://github.com/Azure/azure-functions-durable-extension/tree/v2.2.2/src/WebJobs.Extensions.DurableTask) | | Functions extension for Durable Task Framework - isolated worker | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.DurableTask/1.1.0)
NuGet [1.2.0-rc.1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.DurableTask/1.2.0-rc.1) | | | @@ -445,7 +446,7 @@ | Functions extension for script abstractions | NuGet [1.0.4-preview](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.Abstractions/1.0.4-preview) | | | | Functions extension for SendGrid | NuGet [3.0.3](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SendGrid/3.0.3) | | GitHub [3.0.3](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.SendGrid) | | Functions extension for Sources | NuGet [3.0.39](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Sources/3.0.39) | | GitHub [3.0.39](https://github.com/Azure/azure-webjobs-sdk) | -| Functions extension for Storage Queues | NuGet [5.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/5.2.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Queues-readme) | | +| Functions extension for Storage Queues | NuGet [5.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/5.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Queues-readme) | | | Functions extension for Storage Timers | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Timers.Storage/1.0.0) | | | | Functions extension for Twilio | NuGet [3.0.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Twilio/3.0.2) | | GitHub [3.0.2](https://github.com/Azure/azure-webjobs-sdk-extensions/tree/v3.0.0/src/WebJobs.Extensions.Twilio) | | Functions extension metadata generator | NuGet [4.0.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Script.ExtensionsMetadataGenerator/4.0.1) | | GitHub [4.0.1](https://github.com/Azure/azure-functions-host) | @@ -469,9 +470,9 @@ | Microsoft.Azure.Cosmos.Templates | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Templates/1.0.0) | | | | Microsoft.Azure.Functions.Analyzers | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Analyzers/1.0.0) | | | | Microsoft.Azure.Functions.Authentication.WebAssembly | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Authentication.WebAssembly/1.0.0)
NuGet [1.0.1-preview](https://www.nuget.org/packages/Microsoft.Azure.Functions.Authentication.WebAssembly/1.0.1-preview) | | | -| Microsoft.Azure.Functions.Worker | NuGet [1.21.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker/1.21.0) | | | +| Microsoft.Azure.Functions.Worker | NuGet [1.22.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker/1.22.0) | | | | Microsoft.Azure.Functions.Worker.ApplicationInsights | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.ApplicationInsights/1.2.0) | | | -| Microsoft.Azure.Functions.Worker.Core | NuGet [1.17.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Core/1.17.0) | | | +| Microsoft.Azure.Functions.Worker.Core | NuGet [1.18.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Core/1.18.0) | | | | Microsoft.Azure.Functions.Worker.Extensions.Abstractions | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Abstractions/1.3.0) | | | | Microsoft.Azure.Functions.Worker.Extensions.ApplicationInsights | NuGet [1.0.0-preview4](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.ApplicationInsights/1.0.0-preview4) | | | | Microsoft.Azure.Functions.Worker.Extensions.CosmosDB | NuGet [4.8.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.CosmosDB/4.8.0) | | | @@ -487,9 +488,9 @@ | Microsoft.Azure.Functions.Worker.Extensions.ServiceBus | NuGet [5.17.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.ServiceBus/5.17.0) | | | | Microsoft.Azure.Functions.Worker.Extensions.SignalRService | NuGet [1.13.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.SignalRService/1.13.0) | | | | Microsoft.Azure.Functions.Worker.Extensions.Sql | NuGet [3.0.534](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Sql/3.0.534) | | | -| Microsoft.Azure.Functions.Worker.Extensions.Storage | NuGet [6.3.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage/6.3.0) | | | -| Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs | NuGet [6.3.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs/6.3.0) | | | -| Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues | NuGet [5.3.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues/5.3.0) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Storage | NuGet [6.4.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage/6.4.0) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs | NuGet [6.4.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs/6.4.0) | | | +| Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues | NuGet [5.4.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues/5.4.0) | | | | Microsoft.Azure.Functions.Worker.Extensions.Storage.Tables | NuGet [1.0.0-preview1](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Storage.Tables/1.0.0-preview1) | | | | Microsoft.Azure.Functions.Worker.Extensions.Tables | NuGet [1.3.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Tables/1.3.0) | | | | Microsoft.Azure.Functions.Worker.Extensions.Timer | NuGet [4.3.0](https://www.nuget.org/packages/Microsoft.Azure.Functions.Worker.Extensions.Timer/4.3.0) | | | @@ -506,12 +507,12 @@ | Microsoft.Azure.WebJobs.Extensions.Rpc | NuGet [3.0.39](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Rpc/3.0.39) | | | | Microsoft.Azure.WebJobs.Rpc.Core | NuGet [3.0.39](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Rpc.Core/3.0.39) | | | | Service Bus - Message ID plugin | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.ServiceBus.MessageIdPlugin/2.0.0) | | | -| SignalR | NuGet [1.25.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR/1.25.1)
NuGet [1.25.0-preview1-11147](https://www.nuget.org/packages/Microsoft.Azure.SignalR/1.25.0-preview1-11147) | | GitHub [1.25.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR) | -| SignalR - ASP.NET | NuGet [1.25.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.AspNet/1.25.1) | | GitHub [1.25.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.AspNet) | +| SignalR | NuGet [1.25.2](https://www.nuget.org/packages/Microsoft.Azure.SignalR/1.25.2)
NuGet [1.25.0-preview1-11147](https://www.nuget.org/packages/Microsoft.Azure.SignalR/1.25.0-preview1-11147) | | GitHub [1.25.2](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR) | +| SignalR - ASP.NET | NuGet [1.25.2](https://www.nuget.org/packages/Microsoft.Azure.SignalR.AspNet/1.25.2) | | GitHub [1.25.2](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.AspNet) | | SignalR - Benchmark | NuGet [1.0.0-preview1-10415](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Benchmark/1.0.0-preview1-10415) | | GitHub [1.0.0-preview1-10415](https://github.com/azure/azure-signalr-bench) | -| SignalR - Protocols | NuGet [1.25.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Protocols/1.25.1) | | GitHub [1.25.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Protocols) | +| SignalR - Protocols | NuGet [1.25.2](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Protocols/1.25.2) | | GitHub [1.25.2](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Protocols) | | SignalR - Serverless Protocols | NuGet [1.10.0](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Serverless.Protocols/1.10.0) | | GitHub [1.10.0](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/Microsoft.Azure.SignalR.Serverless.Protocols) | -| SignalR Management | NuGet [1.25.1](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management/1.25.1) | | GitHub [1.25.1](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Management) | +| SignalR Management | NuGet [1.25.2](https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management/1.25.2) | | GitHub [1.25.2](https://github.com/Azure/azure-signalr/tree/v1.5.0/src/Microsoft.Azure.SignalR.Management) | | SQL Database Elastic Scale Client | NuGet [2.4.1](https://www.nuget.org/packages/Microsoft.Azure.SqlDatabase.ElasticScale.Client/2.4.1) | | GitHub [2.4.1](https://github.com/Azure/elastic-db-tools/tree/v2.3.0/Src/ElasticScale.Client) | | SQL Database Elastic Scale Service SplitMerge | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.SqlDatabase.ElasticScale.Service.SplitMerge/1.2.0) | | | | SQL Database Jobs | NuGet [0.8.3362.1](https://www.nuget.org/packages/Microsoft.Azure.SqlDatabase.Jobs/0.8.3362.1) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index a9daa9547552b..71b365faa1301 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -1,7 +1,7 @@ | Name | Package | Docs | Source | | ---- | ------- | ---- | ------ | | Anomaly Detector | NuGet [3.0.0-preview.7](https://www.nuget.org/packages/Azure.AI.AnomalyDetector/3.0.0-preview.7) | [docs](/dotnet/api/overview/azure/AI.AnomalyDetector-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [3.0.0-preview.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AnomalyDetector_3.0.0-preview.7/sdk/anomalydetector/Azure.AI.AnomalyDetector/) | -| App Configuration | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.4.0) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.4.0/sdk/appconfiguration/Azure.Data.AppConfiguration/) | +| App Configuration | NuGet [1.4.1](https://www.nuget.org/packages/Azure.Data.AppConfiguration/1.4.1) | [docs](/dotnet/api/overview/azure/Data.AppConfiguration-readme) | GitHub [1.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Data.AppConfiguration_1.4.1/sdk/appconfiguration/Azure.Data.AppConfiguration/) | | App Configuration Provider | NuGet [7.0.0](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.AzureAppConfiguration/7.0.0)
NuGet [7.1.0-preview](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.AzureAppConfiguration/7.1.0-preview) | | GitHub [7.0.0](https://github.com/Azure/AppConfiguration-DotnetProvider) | | Attestation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Security.Attestation/1.0.0) | [docs](/dotnet/api/overview/azure/Security.Attestation-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.Attestation_1.0.0/sdk/attestation/Azure.Security.Attestation/) | | Azure AI Search | NuGet [11.5.1](https://www.nuget.org/packages/Azure.Search.Documents/11.5.1)
NuGet [11.6.0-beta.3](https://www.nuget.org/packages/Azure.Search.Documents/11.6.0-beta.3) | [docs](/dotnet/api/overview/azure/Search.Documents-readme) | GitHub [11.5.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.5.1/sdk/search/Azure.Search.Documents/)
GitHub [11.6.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Search.Documents_11.6.0-beta.3/sdk/search/Azure.Search.Documents/) | @@ -9,7 +9,7 @@ | Azure Remote Rendering | NuGet [1.1.0](https://www.nuget.org/packages/Azure.MixedReality.RemoteRendering/1.1.0) | [docs](/dotnet/api/overview/azure/MixedReality.RemoteRendering-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.RemoteRendering_1.1.0/sdk/remoterendering/Azure.MixedReality.RemoteRendering/) | | Code Transparency | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Security.CodeTransparency/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Security.CodeTransparency-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.CodeTransparency_1.0.0-beta.2/sdk/confidentialledger/Azure.Security.CodeTransparency/) | | Communication Call Automation | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.1.0) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.1.0/sdk/communication/Azure.Communication.CallAutomation/) | -| Communication Chat | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Communication.Chat/1.2.0) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.2.0/sdk/communication/Azure.Communication.Chat/) | +| Communication Chat | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.0) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.0/sdk/communication/Azure.Communication.Chat/) | | Communication Common | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Common/1.3.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Common/2.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.3.0/sdk/communication/Azure.Communication.Common/)
GitHub [2.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_2.0.0-beta.1/sdk/communication/Azure.Communication.Common/) | | Communication Email | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Email/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Email-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.0.1/sdk/communication/Azure.Communication.Email/) | | Communication Identity | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.3.1/sdk/communication/Azure.Communication.Identity/) | @@ -17,16 +17,18 @@ | Communication Messages | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Communication.Messages/1.0.0) | [docs](/dotnet/api/overview/azure/Communication.Messages-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Messages_1.0.0/sdk/communication/Azure.Communication.Messages/) | | Communication Network Traversal | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Communication.NetworkTraversal/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.NetworkTraversal/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.NetworkTraversal-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.NetworkTraversal_1.0.0/sdk/communication/Azure.Communication.NetworkTraversal/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.NetworkTraversal_1.1.0-beta.1/sdk/communication/Azure.Communication.NetworkTraversal/) | | Communication Phone Numbers | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.1.0)
NuGet [1.3.0-beta.5](https://www.nuget.org/packages/Azure.Communication.PhoneNumbers/1.3.0-beta.5) | [docs](/dotnet/api/overview/azure/Communication.PhoneNumbers-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.1.0/sdk/communication/Azure.Communication.PhoneNumbers/)
GitHub [1.3.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.PhoneNumbers_1.3.0-beta.5/sdk/communication/Azure.Communication.PhoneNumbers/) | -| Communication Rooms | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Communication.Rooms/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Rooms/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Rooms-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Rooms_1.0.0/sdk/communication/Azure.Communication.Rooms/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Rooms_1.1.0-beta.1/sdk/communication/Azure.Communication.Rooms/) | -| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/) | +| Communication Rooms | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Communication.Rooms/1.1.0) | [docs](/dotnet/api/overview/azure/Communication.Rooms-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Rooms_1.1.0/sdk/communication/Azure.Communication.Rooms/) | +| Communication SMS | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Sms/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Sms-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.0.1/sdk/communication/Azure.Communication.Sms/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Sms_1.1.0-beta.1/sdk/communication/Azure.Communication.Sms/) | | Confidential Ledger | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Security.ConfidentialLedger/1.3.0) | [docs](/dotnet/api/overview/azure/Security.ConfidentialLedger-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.ConfidentialLedger_1.3.0/sdk/confidentialledger/Azure.Security.ConfidentialLedger/) | | Container Registry | NuGet [1.1.1](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.1.1)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.Containers.ContainerRegistry/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Containers.ContainerRegistry-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.1.1/sdk/containerregistry/Azure.Containers.ContainerRegistry/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Containers.ContainerRegistry_1.2.0-beta.1/sdk/containerregistry/Azure.Containers.ContainerRegistry/) | | Content Safety | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.ContentSafety/1.0.0) | [docs](/dotnet/api/overview/azure/AI.ContentSafety-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.ContentSafety_1.0.0/sdk/contentsafety/Azure.AI.ContentSafety/) | | Conversational Language Understanding | NuGet [1.1.0](https://www.nuget.org/packages/Azure.AI.Language.Conversations/1.1.0) | [docs](/dotnet/api/overview/azure/AI.Language.Conversations-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Language.Conversations_1.1.0/sdk/cognitivelanguage/Azure.AI.Language.Conversations/) | | Core - Client - AMQP | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Core.Amqp/1.3.0) | [docs](/dotnet/api/overview/azure/Core.Amqp-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Amqp_1.3.0/sdk/core/Azure.Core.Amqp/) | -| Core - Client - Core | NuGet [1.38.0](https://www.nuget.org/packages/Azure.Core/1.38.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.38.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.38.0/sdk/core/Azure.Core/) | +| Core - Client - Core | NuGet [1.39.0](https://www.nuget.org/packages/Azure.Core/1.39.0) | [docs](/dotnet/api/overview/azure/Core-readme) | GitHub [1.39.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core_1.39.0/sdk/core/Azure.Core/) | | Core Newtonsoft Json | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.NewtonsoftJson/2.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.NewtonsoftJson-readme) | GitHub [2.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.NewtonsoftJson_2.0.0/sdk/core/Microsoft.Azure.Core.NewtonsoftJson/) | | Data Movement | NuGet [12.0.0-beta.4](https://www.nuget.org/packages/Azure.Storage.DataMovement/12.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.DataMovement-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.DataMovement_12.0.0-beta.4/sdk/storage/Azure.Storage.DataMovement/) | +| Data Movement - Blobs | NuGet [12.0.0-beta.4](https://www.nuget.org/packages/Azure.Storage.DataMovement.Blobs/12.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Storage.DataMovement.Blobs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.DataMovement.Blobs_12.0.0-beta.4/sdk/storage/Azure.Storage.DataMovement.Blobs/) | +| Data Movement - Files Shares | NuGet [12.0.0-beta.1](https://www.nuget.org/packages/Azure.Storage.DataMovement.Files.Shares/12.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.DataMovement.Files.Shares-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.DataMovement.Files.Shares_12.0.0-beta.1/sdk/storage/Azure.Storage.DataMovement.Files.Shares/) | | Defender EASM | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Defender.Easm/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Defender.Easm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Defender.Easm_1.0.0-beta.1/sdk/easm/Azure.Analytics.Defender.Easm/) | | Dev Center | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Developer.DevCenter/1.0.0) | [docs](/dotnet/api/overview/azure/Developer.DevCenter-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.DevCenter_1.0.0/sdk/devcenter/Azure.Developer.DevCenter/) | | Device Update | NuGet [1.0.0](https://www.nuget.org/packages/Azure.IoT.DeviceUpdate/1.0.0) | [docs](/dotnet/api/overview/azure/IoT.DeviceUpdate-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.DeviceUpdate_1.0.0/sdk/deviceupdate/Azure.IoT.DeviceUpdate/) | @@ -34,7 +36,7 @@ | Document Intelligence | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.DocumentIntelligence/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.DocumentIntelligence-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.DocumentIntelligence_1.0.0-beta.2/sdk/documentintelligence/Azure.AI.DocumentIntelligence/) | | Document Translation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0/sdk/translation/Azure.AI.Translation.Document/) | | Event Grid | NuGet [4.24.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.24.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.24.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.24.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | -| Event Grid Namespaces | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventGrid.Namespaces/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid.Namespaces_1.0.0-beta.1/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/) | +| Event Grid Namespaces | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventGrid.Namespaces/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid.Namespaces-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid.Namespaces_1.0.0-beta.1/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/) | | Event Hubs | NuGet [5.11.2](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.11.2) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.11.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.11.2/sdk/eventhub/Azure.Messaging.EventHubs/) | | Event Hubs - Event Processor | NuGet [5.11.2](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.11.2) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.11.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.11.2/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | | FarmBeats | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Verticals.AgriFood.Farming/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Verticals.AgriFood.Farming-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Verticals.AgriFood.Farming_1.0.0-beta.2/sdk/agrifood/Azure.Verticals.AgriFood.Farming/) | @@ -42,7 +44,7 @@ | Health Insights Cancer Profiling | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.CancerProfiling/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.CancerProfiling-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.CancerProfiling_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.CancerProfiling/) | | Health Insights Clinical Matching | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.ClinicalMatching/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.ClinicalMatching-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.ClinicalMatching_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.ClinicalMatching/) | | Health Insights Radiology Insights | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Health.Insights.RadiologyInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Health.Insights.RadiologyInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Health.Insights.RadiologyInsights_1.0.0-beta.1/sdk/healthinsights/Azure.Health.Insights.RadiologyInsights/) | -| Identity | NuGet [1.11.0](https://www.nuget.org/packages/Azure.Identity/1.11.0) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.11.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.11.0/sdk/identity/Azure.Identity/) | +| Identity | NuGet [1.11.2](https://www.nuget.org/packages/Azure.Identity/1.11.2)
NuGet [1.12.0-beta.1](https://www.nuget.org/packages/Azure.Identity/1.12.0-beta.1) | [docs](/dotnet/api/overview/azure/Identity-readme) | GitHub [1.11.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.11.2/sdk/identity/Azure.Identity/)
GitHub [1.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity_1.12.0-beta.1/sdk/identity/Azure.Identity/) | | Identity Broker | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Identity.Broker/1.1.0) | [docs](/dotnet/api/overview/azure/Identity.Broker-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity.Broker_1.1.0/sdk/identity/Azure.Identity.Broker/) | | Identity Brokered Authentication | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Identity.BrokeredAuthentication/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Identity.BrokeredAuthentication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Identity.BrokeredAuthentication_1.0.0-beta.4/sdk/identity/Azure.Identity.BrokeredAuthentication/) | | Image Analysis | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Vision.ImageAnalysis/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Vision.ImageAnalysis-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/vision/Azure.AI.Vision.ImageAnalysis) | @@ -58,13 +60,13 @@ | Maps Search | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Maps.Search/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Maps.Search-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Maps.Search_1.0.0-beta.4/sdk/maps/Azure.Maps.Search/) | | Media Analytics Edge | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Media.Analytics.Edge/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Media.Analytics.Edge-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.Analytics.Edge_1.0.0-beta.1/sdk/mediaservices/Azure.Media.Analytics.Edge) | | Metrics Advisor | NuGet [1.1.0](https://www.nuget.org/packages/Azure.AI.MetricsAdvisor/1.1.0) | [docs](/dotnet/api/overview/azure/AI.MetricsAdvisor-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.MetricsAdvisor_1.1.0/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/) | -| Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents_1.0.0-beta.6/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/) | +| Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents | NuGet [1.0.0-beta.7](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/1.0.0-beta.7) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents_1.0.0-beta.7/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents/) | | Mixed Reality Authentication | NuGet [1.2.0](https://www.nuget.org/packages/Azure.MixedReality.Authentication/1.2.0) | [docs](/dotnet/api/overview/azure/MixedReality.Authentication-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.MixedReality.Authentication_1.2.0/sdk/mixedreality/Azure.MixedReality.Authentication/) | | Monitor Ingestion | NuGet [1.1.2](https://www.nuget.org/packages/Azure.Monitor.Ingestion/1.1.2) | [docs](/dotnet/api/overview/azure/Monitor.Ingestion-readme) | GitHub [1.1.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.Ingestion_1.1.2/sdk/monitor/Azure.Monitor.Ingestion/) | | Monitor Query | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Monitor.Query/1.3.1) | [docs](/dotnet/api/overview/azure/Monitor.Query-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.Query_1.3.1/sdk/monitor/Azure.Monitor.Query/) | | OpenAI Assistants | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.OpenAI.Assistants/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.OpenAI.Assistants-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI.Assistants_1.0.0-beta.3/sdk/openai/Azure.AI.OpenAI.Assistants/) | | OpenAI Inference | NuGet [1.0.0-beta.16](https://www.nuget.org/packages/Azure.AI.OpenAI/1.0.0-beta.16) | [docs](/dotnet/api/overview/azure/AI.OpenAI-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.16](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.OpenAI_1.0.0-beta.16/sdk/openai/Azure.AI.OpenAI/) | -| OpenTelemetry AspNetCore | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.1.0)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.AspNetCore-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.1.0/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.2.0-beta.2/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/) | +| OpenTelemetry AspNetCore | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.1.0)
NuGet [1.2.0-beta.3](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.AspNetCore/1.2.0-beta.3) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.AspNetCore-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.1.0/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/)
GitHub [1.2.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.AspNetCore_1.2.0-beta.3/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/) | | OpenTelemetry Exporter | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.2.0)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.2.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.3.0-beta.1/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | | OpenTelemetry LiveMetrics | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.LiveMetrics/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.LiveMetrics-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.LiveMetrics_1.0.0-beta.3/sdk/monitor/Azure.Monitor.OpenTelemetry.LiveMetrics/) | | Personalizer | NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Personalizer/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Personalizer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Personalizer_2.0.0-beta.2/sdk/personalizer/Azure.AI.Personalizer/) | @@ -80,12 +82,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.1](https://www.nuget.org/packages/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/1.0.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro_1.0.1/sdk/schemaregistry/Microsoft.Azure.Data.SchemaRegistry.ApacheAvro/) | | Service Bus | NuGet [7.17.5](https://www.nuget.org/packages/Azure.Messaging.ServiceBus/7.17.5) | [docs](/dotnet/api/overview/azure/Messaging.ServiceBus-readme) | GitHub [7.17.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.ServiceBus_7.17.5/sdk/servicebus/Azure.Messaging.ServiceBus/) | -| Storage - Blobs | NuGet [12.19.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.19.1)
NuGet [12.20.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.20.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.19.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.19.1/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.20.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.20.0-beta.1/sdk/storage/Azure.Storage.Blobs/) | -| Storage - Blobs Batch | NuGet [12.16.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.16.1)
NuGet [12.17.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.17.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.16.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.16.1/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.17.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.17.0-beta.1/sdk/storage/Azure.Storage.Blobs.Batch/) | -| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.42](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.42) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.42](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.42/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | -| Storage - Files Data Lake | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.17.1)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.17.1/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.18.0-beta.1/sdk/storage/Azure.Storage.Files.DataLake/) | -| Storage - Files Share | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.17.1)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.17.1/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.18.0-beta.1/sdk/storage/Azure.Storage.Files.Shares/) | -| Storage - Queues | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.17.1)
NuGet [12.18.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.18.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.17.1/sdk/storage/Azure.Storage.Queues/)
GitHub [12.18.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.18.0-beta.1/sdk/storage/Azure.Storage.Queues/) | +| Storage - Blobs | NuGet [12.19.1](https://www.nuget.org/packages/Azure.Storage.Blobs/12.19.1)
NuGet [12.20.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Blobs/12.20.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Blobs-readme) | GitHub [12.19.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.19.1/sdk/storage/Azure.Storage.Blobs/)
GitHub [12.20.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs_12.20.0-beta.2/sdk/storage/Azure.Storage.Blobs/) | +| Storage - Blobs Batch | NuGet [12.16.1](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.16.1)
NuGet [12.17.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Blobs.Batch/12.17.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Blobs.Batch-readme) | GitHub [12.16.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.16.1/sdk/storage/Azure.Storage.Blobs.Batch/)
GitHub [12.17.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.Batch_12.17.0-beta.2/sdk/storage/Azure.Storage.Blobs.Batch/) | +| Storage - Blobs ChangeFeed | NuGet [12.0.0-preview.43](https://www.nuget.org/packages/Azure.Storage.Blobs.ChangeFeed/12.0.0-preview.43) | [docs](/dotnet/api/overview/azure/Storage.Blobs.ChangeFeed-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [12.0.0-preview.43](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Blobs.ChangeFeed_12.0.0-preview.43/sdk/storage/Azure.Storage.Blobs.ChangeFeed/) | +| Storage - Files Data Lake | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.17.1)
NuGet [12.18.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Files.DataLake/12.18.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Files.DataLake-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.17.1/sdk/storage/Azure.Storage.Files.DataLake/)
GitHub [12.18.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.DataLake_12.18.0-beta.2/sdk/storage/Azure.Storage.Files.DataLake/) | +| Storage - Files Share | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.17.1)
NuGet [12.18.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Files.Shares/12.18.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Files.Shares-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.17.1/sdk/storage/Azure.Storage.Files.Shares/)
GitHub [12.18.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Files.Shares_12.18.0-beta.2/sdk/storage/Azure.Storage.Files.Shares/) | +| Storage - Queues | NuGet [12.17.1](https://www.nuget.org/packages/Azure.Storage.Queues/12.17.1)
NuGet [12.18.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Queues/12.18.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Queues-readme) | GitHub [12.17.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.17.1/sdk/storage/Azure.Storage.Queues/)
GitHub [12.18.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Queues_12.18.0-beta.2/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.19](https://www.nuget.org/packages/Azure.Analytics.Synapse.Artifacts/1.0.0-preview.19) | [docs](/dotnet/api/overview/azure/Analytics.Synapse.Artifacts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.19](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Synapse.Artifacts_1.0.0-preview.19/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/) | @@ -97,27 +99,27 @@ | Text Translation | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Translation.Text/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Translation.Text-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Text_1.0.0-beta.1/sdk/translation/Azure.AI.Translation.Text/) | | unknown | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.CallingServer/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.CallingServer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallingServer_1.0.0-beta.3/sdk/communication/Azure.Communication.CallingServer/) | | unknown | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Core.Expressions.DataFactory/1.0.0) | [docs](/dotnet/api/overview/azure/Core.Expressions.DataFactory-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Core.Expressions.DataFactory_1.0.0/sdk/core/Azure.Core.Expressions.DataFactory/) | -| unknown | NuGet [1.0.0-preview.5](https://www.nuget.org/packages/Azure.IoT.ModelsRepository/1.0.0-preview.5) | [docs](/dotnet/api/overview/azure/IoT.ModelsRepository-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.ModelsRepository_1.0.0-preview.5/sdk/modelsrepository/Azure.IoT.ModelsRepository/) | +| unknown | NuGet [1.0.0-preview.6](https://www.nuget.org/packages/Azure.IoT.ModelsRepository/1.0.0-preview.6) | [docs](/dotnet/api/overview/azure/IoT.ModelsRepository-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-preview.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.ModelsRepository_1.0.0-preview.6/sdk/modelsrepository/Azure.IoT.ModelsRepository/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.IoT.TimeSeriesInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/IoT.TimeSeriesInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.IoT.TimeSeriesInsights_1.0.0-beta.1/sdk/timeseriesinsights/Azure.IoT.TimeSeriesInsights/) | | unknown | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Quantum.Jobs/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Quantum.Jobs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Quantum.Jobs_1.0.0-beta.3/sdk/quantum/Azure.Quantum.Jobs/) | | Video Analyzer Edge | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.Media.VideoAnalyzer.Edge/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/Media.VideoAnalyzer.Edge-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Media.VideoAnalyzer.Edge_1.0.0-beta.6/sdk/videoanalyzer/Azure.Media.VideoAnalyzer.Edge/) | | Vision Common | NuGet [0.15.1-beta.1](https://www.nuget.org/packages/Azure.AI.Vision.Common/0.15.1-beta.1) | | GitHub [0.15.1-beta.1](https://msasg.visualstudio.com/Skyman/_git/Carbon) | | Web PubSub | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub/1.3.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub_1.3.0/sdk/webpubsub/Azure.Messaging.WebPubSub/) | | Web PubSub Client | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub.Client/1.0.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub.Client-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub.Client_1.0.0/sdk/webpubsub/Azure.Messaging.WebPubSub.Client/) | -| Azure client library integration for ASP.NET Core | NuGet [1.7.2](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.2) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.2/sdk/extensions/Microsoft.Extensions.Azure/) | -| Blob Storage Key Store for .NET Data Protection | NuGet [1.3.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.3.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.3.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.3.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | +| Azure client library integration for ASP.NET Core | NuGet [1.7.3](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.3) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.3](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.3/sdk/extensions/Microsoft.Extensions.Azure/) | +| Blob Storage Key Store for .NET Data Protection | NuGet [1.3.4](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.3.4) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.3.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.3.4/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | | CloudNative CloudEvents with Event Grid | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/1.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents_1.0.0/sdk/eventgrid/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/) | | Core - Client - Spatial | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.Spatial-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.1.0/sdk/core/Microsoft.Azure.Core.Spatial/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.2.0-beta.1/sdk/core/Microsoft.Azure.Core.Spatial/) | | Core - Client - Spatial Newtonsoft Json | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial.NewtonsoftJson/1.0.0)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial.NewtonsoftJson/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.Spatial.NewtonsoftJson-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial.NewtonsoftJson_1.0.0/sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial.NewtonsoftJson_1.1.0-beta.1/sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/) | -| Functions extension for Azure Tables | NuGet [1.2.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Tables/1.2.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Tables-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Tables_1.2.1/sdk/tables/Microsoft.Azure.WebJobs.Extensions.Tables/) | +| Functions extension for Azure Tables | NuGet [1.3.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Tables/1.3.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Tables-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Tables_1.3.1/sdk/tables/Microsoft.Azure.WebJobs.Extensions.Tables/) | | Key Encryptor for .NET Data Protection | NuGet [1.2.3](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Keys/1.2.3) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Keys-readme) | GitHub [1.2.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Keys_1.2.3/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Keys/) | | Secrets Configuration Provider for .NET | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.Configuration.Secrets/1.3.1) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.Configuration.Secrets-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.Configuration.Secrets_1.3.1/sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/) | -| Storage - Common | NuGet [12.18.1](https://www.nuget.org/packages/Azure.Storage.Common/12.18.1)
NuGet [12.19.0-beta.1](https://www.nuget.org/packages/Azure.Storage.Common/12.19.0-beta.1) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.18.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.18.1/sdk/storage/Azure.Storage.Common/)
GitHub [12.19.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.19.0-beta.1/sdk/storage/Azure.Storage.Common/) | -| WebJobs Extensions - Event Grid | NuGet [3.3.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.3.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventGrid-readme) | GitHub [3.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventGrid_3.3.1/sdk/eventgrid/Microsoft.Azure.WebJobs.Extensions.EventGrid/) | -| WebJobs Extensions - Event Hubs | NuGet [6.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/6.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventHubs-readme) | GitHub [6.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventHubs_6.3.0/sdk/eventhub/Microsoft.Azure.WebJobs.Extensions.EventHubs/) | -| WebJobs Extensions - Service Bus | NuGet [5.14.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.14.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.ServiceBus-readme) | GitHub [5.14.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.14.0/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/) | +| Storage - Common | NuGet [12.18.1](https://www.nuget.org/packages/Azure.Storage.Common/12.18.1)
NuGet [12.19.0-beta.2](https://www.nuget.org/packages/Azure.Storage.Common/12.19.0-beta.2) | [docs](/dotnet/api/overview/azure/Storage.Common-readme) | GitHub [12.18.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.18.1/sdk/storage/Azure.Storage.Common/)
GitHub [12.19.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Storage.Common_12.19.0-beta.2/sdk/storage/Azure.Storage.Common/) | +| WebJobs Extensions - Event Grid | NuGet [3.4.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventGrid/3.4.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventGrid-readme) | GitHub [3.4.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventGrid_3.4.1/sdk/eventgrid/Microsoft.Azure.WebJobs.Extensions.EventGrid/) | +| WebJobs Extensions - Event Hubs | NuGet [6.3.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.EventHubs/6.3.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.EventHubs-readme) | GitHub [6.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.EventHubs_6.3.1/sdk/eventhub/Microsoft.Azure.WebJobs.Extensions.EventHubs/) | +| WebJobs Extensions - Service Bus | NuGet [5.15.1](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.ServiceBus/5.15.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.ServiceBus-readme) | GitHub [5.15.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.ServiceBus_5.15.1/sdk/servicebus/Microsoft.Azure.WebJobs.Extensions.ServiceBus/) | | WebJobs Extensions - SignalR Service | NuGet [1.13.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.SignalRService/1.13.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.SignalRService-readme) | GitHub [1.13.0](https://github.com/Azure/azure-functions-signalrservice-extension/tree/v1.2.0/src/SignalRServiceExtension) | -| WebJobs Extensions - Storage | NuGet [5.2.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/5.2.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage-readme) | GitHub [5.2.2](https://github.com/Azure/azure-webjobs-sdk/tree/master/src/Microsoft.Azure.WebJobs.Extensions.Storage) | +| WebJobs Extensions - Storage | NuGet [5.3.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage/5.3.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage-readme) | GitHub [5.3.0](https://github.com/Azure/azure-webjobs-sdk/tree/master/src/Microsoft.Azure.WebJobs.Extensions.Storage) | | WebJobs Extensions - Web PubSub | NuGet [1.7.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSub/1.7.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.WebPubSub-readme) | GitHub [1.7.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.WebPubSub_1.7.0/sdk/webpubsub/Microsoft.Azure.WebJobs.Extensions.WebPubSub/) | | Provisioning | NuGet [0.2.0-beta.2](https://www.nuget.org/packages/Azure.Provisioning/0.2.0-beta.2) | [docs](/dotnet/api/overview/azure/Provisioning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_0.2.0-beta.2/sdk/provisioning/Azure.Provisioning/) | | Provisioning - App Configuration | NuGet [0.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/0.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_0.1.0-beta.1/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | @@ -140,18 +142,18 @@ | Resource Management - Alerts Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.AlertsManagement/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AlertsManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AlertsManagement_1.1.0/sdk/alertsmanagement/Azure.ResourceManager.AlertsManagement/) | | Resource Management - Analysis | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Analysis/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Analysis-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Analysis_1.1.0/sdk/analysisservices/Azure.ResourceManager.Analysis/) | | Resource Management - API Center | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ApiCenter/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ApiCenter-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiCenter_1.0.0-beta.2/sdk/apicenter/Azure.ResourceManager.ApiCenter/) | -| Resource Management - API Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ApiManagement/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ApiManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiManagement_1.1.0/sdk/apimanagement/Azure.ResourceManager.ApiManagement/) | +| Resource Management - API Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ApiManagement/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ApiManagement/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ApiManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiManagement_1.1.0/sdk/apimanagement/Azure.ResourceManager.ApiManagement/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApiManagement_1.2.0-beta.1/sdk/apimanagement/Azure.ResourceManager.ApiManagement/) | | Resource Management - App Compliance Automation | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.AppComplianceAutomation/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.AppComplianceAutomation-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppComplianceAutomation_1.0.0-beta.4/sdk/appcomplianceautomation/Azure.ResourceManager.AppComplianceAutomation/) | | Resource Management - App Configuration | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.AppConfiguration/1.3.1) | [docs](/dotnet/api/overview/azure/ResourceManager.AppConfiguration-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppConfiguration_1.3.1/sdk/appconfiguration/Azure.ResourceManager.AppConfiguration/) | | Resource Management - App Platform | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.AppPlatform/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AppPlatform-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppPlatform_1.1.0/sdk/appplatform/Azure.ResourceManager.AppPlatform/) | -| Resource Management - App Service | NuGet [1.0.2](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.0.2)
NuGet [1.1.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.1.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.AppService-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.0.2/sdk/websites/Azure.ResourceManager.AppService/)
GitHub [1.1.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.1.0-beta.4/sdk/websites/Azure.ResourceManager.AppService/) | +| Resource Management - App Service | NuGet [1.0.2](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.0.2)
NuGet [1.1.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.AppService/1.1.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.AppService-readme) | GitHub [1.0.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.0.2/sdk/websites/Azure.ResourceManager.AppService/)
GitHub [1.1.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppService_1.1.0-beta.5/sdk/websites/Azure.ResourceManager.AppService/) | | Resource Management - Application Insights | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.ApplicationInsights/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ApplicationInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ApplicationInsights_1.0.0-beta.5/sdk/applicationinsights/Azure.ResourceManager.ApplicationInsights/) | | Resource Management - Arc ScVmm | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.ArcScVmm/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.ArcScVmm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ArcScVmm_1.0.0-beta.4/sdk/arc-scvmm/Azure.ResourceManager.ArcScVmm/) | | Resource Management - Attestation | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.Attestation/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.Attestation-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Attestation_1.0.0-beta.4/sdk/attestation/Azure.ResourceManager.Attestation/) | | Resource Management - Authorization | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Authorization/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Authorization-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Authorization_1.1.1/sdk/authorization/Azure.ResourceManager.Authorization/) | | Resource Management - Automanage | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Automanage/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Automanage-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automanage_1.1.0/sdk/automanage/Azure.ResourceManager.Automanage/) | | Resource Management - Automation | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Automation/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Automation-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Automation_1.1.0/sdk/automation/Azure.ResourceManager.Automation/) | -| Resource Management - Azure AI Search | NuGet [1.2.2](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.2/sdk/search/Azure.ResourceManager.Search/) | +| Resource Management - Azure AI Search | NuGet [1.2.2](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.2.2)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Search/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Search-readme) | GitHub [1.2.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.2.2/sdk/search/Azure.ResourceManager.Search/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Search_1.3.0-beta.1/sdk/search/Azure.ResourceManager.Search/) | | Resource Management - Azure Stack HCI | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Hci/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Hci/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Hci-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Hci_1.1.0/sdk/azurestackhci/Azure.ResourceManager.Hci/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Hci_1.2.0-beta.1/sdk/azurestackhci/Azure.ResourceManager.Hci/) | | Resource Management - Azure VMware Solution | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Avs/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Avs-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Avs_1.3.0/sdk/avs/Azure.ResourceManager.Avs/) | | Resource Management - Batch | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.Batch/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Batch-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Batch_1.4.0/sdk/batch/Azure.ResourceManager.Batch/) | @@ -285,7 +287,7 @@ | Resource Management - Resource Connector | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ResourceConnector/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceConnector-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceConnector_1.0.0-beta.2/sdk/resourceconnector/Azure.ResourceManager.ResourceConnector/) | | Resource Management - Resource Graph | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.ResourceGraph/1.0.1)
NuGet [1.1.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ResourceGraph/1.1.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceGraph-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceGraph_1.0.1/sdk/resourcegraph/Azure.ResourceManager.ResourceGraph/)
GitHub [1.1.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceGraph_1.1.0-beta.2/sdk/resourcegraph/Azure.ResourceManager.ResourceGraph/) | | Resource Management - Resource Health | NuGet [1.0.0](https://www.nuget.org/packages/Azure.ResourceManager.ResourceHealth/1.0.0)
NuGet [1.1.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.ResourceHealth/1.1.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceHealth-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceHealth_1.0.0/sdk/resourcehealth/Azure.ResourceManager.ResourceHealth/)
GitHub [1.1.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceHealth_1.1.0-beta.3/sdk/resourcehealth/Azure.ResourceManager.ResourceHealth/) | -| Resource Management - Resource Manager | NuGet [1.11.0](https://www.nuget.org/packages/Azure.ResourceManager/1.11.0)
NuGet [1.12.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager/1.12.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager-readme) | GitHub [1.11.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.11.0/sdk/resourcemanager/Azure.ResourceManager/)
GitHub [1.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.12.0-beta.1/sdk/resourcemanager/Azure.ResourceManager/) | +| Resource Management - Resource Manager | NuGet [1.11.1](https://www.nuget.org/packages/Azure.ResourceManager/1.11.1)
NuGet [1.12.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager/1.12.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager-readme) | GitHub [1.11.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.11.1/sdk/resourcemanager/Azure.ResourceManager/)
GitHub [1.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager_1.12.0-beta.1/sdk/resourcemanager/Azure.ResourceManager/) | | Resource Management - Resource Mover | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.ResourceMover/1.1.1)
NuGet [1.1.2-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ResourceMover/1.1.2-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ResourceMover-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceMover_1.1.1/sdk/resourcemover/Azure.ResourceManager.ResourceMover/)
GitHub [1.1.2-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ResourceMover_1.1.2-beta.1/sdk/resourcemover/Azure.ResourceManager.ResourceMover/) | | Resource Management - Resources | NuGet [1.7.1](https://www.nuget.org/packages/Azure.ResourceManager.Resources/1.7.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Resources-readme) | GitHub [1.7.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Resources_1.7.1/sdk/resources/Azure.ResourceManager.Resources/) | | Resource Management - ScVmm | NuGet [1.0.0-beta.5](https://www.nuget.org/packages/Azure.ResourceManager.ScVmm/1.0.0-beta.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ScVmm-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ScVmm_1.0.0-beta.5/sdk/arc-scvmm/Azure.ResourceManager.ScVmm/) | @@ -315,6 +317,6 @@ | Resource Management - Synapse | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Synapse/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Synapse-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Synapse_1.2.0/sdk/synapse/Azure.ResourceManager.Synapse/) | | Resource Management - Traffic Manager | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.TrafficManager/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.TrafficManager-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.TrafficManager_1.1.1/sdk/trafficmanager/Azure.ResourceManager.TrafficManager/) | | Resource Management - Voice Services | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.VoiceServices/1.0.1) | [docs](/dotnet/api/overview/azure/ResourceManager.VoiceServices-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.VoiceServices_1.0.1/sdk/voiceservices/Azure.ResourceManager.VoiceServices/) | -| Resource Management - Web PubSub | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.WebPubSub/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.WebPubSub-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WebPubSub_1.1.0/sdk/webpubsub/Azure.ResourceManager.WebPubSub/) | +| Resource Management - Web PubSub | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.WebPubSub/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.WebPubSub/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.WebPubSub-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WebPubSub_1.1.0/sdk/webpubsub/Azure.ResourceManager.WebPubSub/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WebPubSub_1.2.0-beta.1/sdk/webpubsub/Azure.ResourceManager.WebPubSub/) | | Resource Management - Workload Monitor | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.WorkloadMonitor/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.WorkloadMonitor-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.WorkloadMonitor_1.0.0-beta.4/sdk/workloadmonitor/Azure.ResourceManager.WorkloadMonitor/) | | Resource Management - Workloads | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Workloads/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.Workloads/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Workloads-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Workloads_1.1.0/sdk/workloads/Azure.ResourceManager.Workloads/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Workloads_1.2.0-beta.1/sdk/workloads/Azure.ResourceManager.Workloads/) | diff --git a/docs/azure/sdk/snippets/logging/LoggingSampleApp.csproj b/docs/azure/sdk/snippets/logging/LoggingSampleApp.csproj index d7776febea80c..83cc3233ec207 100644 --- a/docs/azure/sdk/snippets/logging/LoggingSampleApp.csproj +++ b/docs/azure/sdk/snippets/logging/LoggingSampleApp.csproj @@ -7,10 +7,10 @@ - + - - + + diff --git a/docs/azure/sdk/snippets/pagination/pagination.csproj b/docs/azure/sdk/snippets/pagination/pagination.csproj index afa3227df8963..49a2edd6d9a12 100644 --- a/docs/azure/sdk/snippets/pagination/pagination.csproj +++ b/docs/azure/sdk/snippets/pagination/pagination.csproj @@ -10,7 +10,7 @@ - + diff --git a/docs/core/additional-tools/self-signed-certificates-guide.md b/docs/core/additional-tools/self-signed-certificates-guide.md index 9bb35706b43d6..70122f7c38c8b 100644 --- a/docs/core/additional-tools/self-signed-certificates-guide.md +++ b/docs/core/additional-tools/self-signed-certificates-guide.md @@ -1,6 +1,6 @@ --- title: Generate Self-Signed Certificates Overview -description: An overview of the Microsoft dotnet dev-certs tool that adds functionality for .NET Core and ASP.NET Core projects, and other options for using self-signed certificates. +description: An overview of the Microsoft dotnet dev-certs tool that adds functionality for .NET and ASP.NET Core projects, and other options for using self-signed certificates. author: angee ms.date: 12/06/2021 --- @@ -13,8 +13,6 @@ You can then validate that the certificate will load using an example such as an ## Prerequisites -In the sample, you can utilize either .NET Core 3.1 or .NET 5. - For `dotnet dev-certs`, be sure to have the appropriate version of .NET installed: * [Install .NET on Windows](../install/windows.md) @@ -25,86 +23,17 @@ This sample requires [Docker 17.06](https://docs.docker.com/release-notes/docker ## Prepare sample app -You'll need to prepare the sample app depending on which runtime you'd like to use for testing, either [.NET Core 3.1](#net-core-31-sample-app) or [.NET 5](#net-5-sample-app). - For this guide, you'll use a [sample app](https://hub.docker.com/_/microsoft-dotnet-samples) and make changes where appropriate. -### .NET Core 3.1 sample app - -Get the sample app. - -```console -git clone https://github.com/dotnet/dotnet-docker/ -``` - -Navigate to the repository locally and open up the workspace in an editor. - -> [!NOTE] -> If you're looking to use dotnet publish parameters to *trim* the deployment, you should make sure that the appropriate dependencies are included for supporting SSL certificates. -Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trimming/trim-self-contained.md) when using trimming for self-contained deployments. - -Make sure the `aspnetapp.csproj` includes the appropriate target framework: - -```xml - - - - .netcoreapp3.1 - - - - -``` - -Modify the Dockerfile to make sure the runtime points to .NET Core 3.1: - -```Dockerfile -# https://hub.docker.com/_/microsoft-dotnet-core -FROM mcr.microsoft.com/dotnet/core/sdk:3.1 AS build -WORKDIR /source - -# copy csproj and restore as distinct layers -COPY *.sln . -COPY aspnetapp/*.csproj ./aspnetapp/ -RUN dotnet restore - -# copy everything else and build app -COPY aspnetapp/. ./aspnetapp/ -WORKDIR /source/aspnetapp -RUN dotnet publish -c release -o /app --no-restore - -# final stage/image -FROM mcr.microsoft.com/dotnet/core/aspnet:3.1 -WORKDIR /app -COPY --from=build /app ./ -ENTRYPOINT ["dotnet", "aspnetapp.dll"] -``` - -Make sure you're pointing to the sample app. - -```console -cd .\dotnet-docker\samples\aspnetapp -``` +Check that the sample app [Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/Dockerfile) is using .NET 8. -Build the container for testing locally. - -```console -docker build -t aspnetapp:my-sample -f Dockerfile . -``` - -### .NET 5 sample app - -For this guide, the [sample aspnetapp](https://hub.docker.com/_/microsoft-dotnet-samples) should be checked for .NET 5. - -Check sample app [Dockerfile](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/Dockerfile) is using .NET 5. - -Depending on the host OS, the ASP.NET runtime may need to be updated. For example, changing from `mcr.microsoft.com/dotnet/aspnet:5.0-nanoservercore-2009 AS runtime` to `mcr.microsoft.com/dotnet/aspnet:5.0-windowsservercore-ltsc2019 AS runtime` in the Dockerfile will help with targeting the appropriate Windows runtime. +Depending on the host OS, you might need to update the ASP.NET runtime. For example, to target the appropriate Windows runtime, change `mcr.microsoft.com/dotnet/aspnet:8.0-nanoservercore-2009 AS runtime` to `mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime` in the Dockerfile. For example, this will help with testing the certificates on Windows: ```Dockerfile # https://hub.docker.com/_/microsoft-dotnet -FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build +FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /source # copy csproj and restore as distinct layers @@ -118,14 +47,13 @@ WORKDIR /source/aspnetapp RUN dotnet publish -c release -o /app -r win-x64 --self-contained false --no-restore # final stage/image -# Uses the 2009 release; 2004, 1909, and 1809 are other choices -FROM mcr.microsoft.com/dotnet/aspnet:5.0-windowsservercore-ltsc2019 AS runtime +FROM mcr.microsoft.com/dotnet/aspnet:8.0-windowsservercore-ltsc2022 AS runtime WORKDIR /app COPY --from=build /app ./ ENTRYPOINT ["aspnetapp"] ``` -If we're testing the certificates on Linux, you can use the existing Dockerfile. +If you're testing the certificates on Linux, you can use the existing Dockerfile. Make sure the `aspnetapp.csproj` includes the appropriate target framework: @@ -133,7 +61,7 @@ Make sure the `aspnetapp.csproj` includes the appropriate target framework: - net5.0 + net8.0 @@ -142,7 +70,7 @@ Make sure the `aspnetapp.csproj` includes the appropriate target framework: > [!NOTE] > If you want to use `dotnet publish` parameters to *trim* the deployment, make sure that the appropriate dependencies are included for supporting SSL certificates. -Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trimming/trim-self-contained.md) when using trimming for self-contained deployments. +Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) file to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support SSL certificates](../deploying/trimming/trim-self-contained.md) when using trimming for self-contained deployments. Make sure you're pointing to the sample app. @@ -228,7 +156,7 @@ docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http:// ``` > [!NOTE] -> Note that with the volume mount the file path could be handled differently based on host. For example, in WSL we may replace */c/certs* with */mnt/c/certs*. +> Note that with the volume mount, the file path could be handled differently based on host. For example, in WSL you might replace */c/certs* with */mnt/c/certs*. If you're using the container built earlier for Windows, the run command would look like the following: @@ -250,9 +178,9 @@ $rootCert | Remove-item ### With OpenSSL -You can use [OpenSSL](https://www.openssl.org/) to create self-signed certificates. This example will use WSL / Ubuntu and a bash shell with `OpenSSL`. +You can use [OpenSSL](https://www.openssl.org/) to create self-signed certificates. This example uses WSL / Ubuntu and a bash shell with `OpenSSL`. -This will generate a .crt and a .key. +This command generates a .crt and a .key. ```bash PARENT="contoso.com" @@ -297,9 +225,9 @@ openssl pkcs12 -export -out $PARENT.pfx -inkey $PARENT.key -in $PARENT.crt ``` > [!NOTE] -> The .aspnetcore 3.1 example will use `.pfx` and a password. Starting with the `.net 5` runtime, Kestrel can also take `.crt` and PEM-encoded `.key` files. +> Starting in .NET 5, Kestrel can take *.crt* and PEM-encoded *.key* files in addition to *.pfx* files with a password. -Depending on the host os, the certificate will need to be trusted. On a Linux host, 'trusting' the certificate is different and distro dependent. +Depending on the host OS, the certificate needs to be trusted. On a Linux host, 'trusting' the certificate is different and distro dependent. For the purposes of this guide, here's an example in Windows using PowerShell: @@ -307,28 +235,16 @@ For the purposes of this guide, here's an example in Windows using PowerShell: Import-Certificate -FilePath $certKeyPath -CertStoreLocation 'Cert:\LocalMachine\Root' ``` -For .NET Core 3.1, run the following command in WSL: - -```bash -docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/contoso.com.pfx -v /c/path/to/certs/:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp -``` - -Starting with .NET 5, Kestrel can take the `.crt` and PEM-encoded `.key` files. You can run the sample with the following command for .NET 5: +Run the sample using the following command in WSL: ```bash docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/contoso.com.crt -e ASPNETCORE_Kestrel__Certificates__Default__KeyPath=/https/contoso.com.key -v /c/path/to/certs:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp ``` > [!NOTE] -> Note that in WSL, the volume mount path may change depending on the configuration. - -For .NET Core 3.1 in Windows, run the following command in `Powershell`: - -```powershell -docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\contoso.com.pfx -v c:\certs:C:\https aspnetapp:my-sample -``` +> In WSL, the volume mount path might change depending on the configuration. -For .NET 5 in Windows, run the following command in PowerShell: +Run the following command in PowerShell: ```powershell docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\contoso.com.crt -e ASPNETCORE_Kestrel__Certificates__Default__KeyPath=c:\https\contoso.com.key -v c:\certs:C:\https aspnetapp:my-sample diff --git a/docs/core/additional-tools/xml-serializer-generator.md b/docs/core/additional-tools/xml-serializer-generator.md index ba5e2ad2f6d72..cab05fde355a1 100644 --- a/docs/core/additional-tools/xml-serializer-generator.md +++ b/docs/core/additional-tools/xml-serializer-generator.md @@ -2,23 +2,23 @@ title: "Microsoft XML Serializer Generator" description: An overview of the Microsoft XML Serializer Generator. Use the XML Serializer Generator to generate an XML serialization assembly for the types contained in your project. author: honggit -ms.date: 01/19/2017 +ms.date: 04/23/2024 ms.topic: tutorial ms.custom: "mvc" --- -# Using Microsoft XML Serializer Generator on .NET Core +# Use Microsoft XML Serializer Generator on .NET Core -This tutorial teaches you how to use the Microsoft XML Serializer Generator in a C# .NET Core application. During the course of this tutorial, you learn: +In this tutorial, you learn how to use the Microsoft XML Serializer Generator in a C# application. During the course of this tutorial, you learn: > [!div class="checklist"] > -> - How to create a .NET Core app +> - How to create a .NET console app > - How to add a reference to the Microsoft.XmlSerializer.Generator package > - How to edit your MyApp.csproj to add dependencies > - How to add a class and an XmlSerializer > - How to build and run the application -Like the [Xml Serializer Generator (sgen.exe)](../../standard/serialization/xml-serializer-generator-tool-sgen-exe.md) for the .NET Framework, the [Microsoft.XmlSerializer.Generator NuGet package](https://www.nuget.org/packages/Microsoft.XmlSerializer.Generator) is the equivalent for .NET Core and .NET Standard projects. It creates an XML serialization assembly for types contained in an assembly to improve the startup performance of XML serialization when serializing or de-serializing objects of those types using . +Like the [Xml Serializer Generator (sgen.exe)](../../standard/serialization/xml-serializer-generator-tool-sgen-exe.md) for .NET Framework, the [Microsoft.XmlSerializer.Generator NuGet package](https://www.nuget.org/packages/Microsoft.XmlSerializer.Generator) is the equivalent for .NET Core/.NET 5+ and .NET Standard projects. It creates an XML serialization assembly for types contained in an assembly to improve the startup performance of XML serialization when serializing or de-serializing objects of those types using . ## Prerequisites @@ -30,97 +30,77 @@ To complete this tutorial: > [!TIP] > Need to install a code editor? Try [Visual Studio](https://aka.ms/vsdownload?utm_source=mscom&utm_campaign=msdocs)! -## Use Microsoft XML Serializer Generator in a .NET Core console application - The following instructions show you how to use XML Serializer Generator in a .NET Core console application. -### Create a .NET Core console application - -Open a command prompt and create a folder named *MyApp*. Navigate to the folder you created and type the following command: - -```dotnetcli -dotnet new console -``` - -### Add a reference to the Microsoft.XmlSerializer.Generator package in the MyApp project - -Use the [`dotnet add package`](../tools/dotnet-add-package.md) command to add the reference in your project. +## Create the app -Type: +1. Open a command prompt and create a folder named *MyApp*. Navigate to the folder you created and type the following command: -```dotnetcli -dotnet add package Microsoft.XmlSerializer.Generator -v 1.0.0 -``` + ```dotnetcli + dotnet new console + ``` -### Verify changes to MyApp.csproj after adding the package +2. Use the [`dotnet add package`](../tools/dotnet-add-package.md) command to add a reference to the Microsoft.XmlSerializer.Generator package. -Open your code editor and let's get started! We're still working from the *MyApp* directory we built the app in. + ```dotnetcli + dotnet add package Microsoft.XmlSerializer.Generator -v 8.0.0 + ``` -Open *MyApp.csproj* in your text editor. + After running the [`dotnet add package`](../tools/dotnet-add-package.md) command, the following lines are added to your *MyApp.csproj* project file: -After running the [`dotnet add package`](../tools/dotnet-add-package.md) command, the following lines are added to your *MyApp.csproj* project file: + ```xml + + + + ``` - ```xml - - - - ``` +3. Add a tool reference by adding the following `ItemGroup` section to your project file. -### Add another ItemGroup section for .NET CLI Tool support + ```xml + + + + ``` -Add the following lines after the `ItemGroup` section that we inspected: +4. Open *Program.cs* in your text editor. Add a class named *MyClass* in *Program.cs*. - ```xml - - - - ``` + ```csharp + public class MyClass + { + public int Value; + } + ``` -### Add a class in the application +5. Create an `XmlSerializer` for `MyClass`. Add the following line to the *Program.cs* file: -Open *Program.cs* in your text editor. Add the class named *MyClass* in *Program.cs*. + ```csharp + var serializer = new System.Xml.Serialization.XmlSerializer(typeof(MyClass)); + ``` -```csharp -public class MyClass -{ - public int Value; -} -``` +6. Build and run the application. Run the application via [`dotnet run`](../tools/dotnet-run.md): -### Create an `XmlSerializer` for MyClass + ```dotnetcli + dotnet run + ``` -Add the following line inside *Main* to create an `XmlSerializer` for MyClass: - -```csharp -var serializer = new System.Xml.Serialization.XmlSerializer(typeof(MyClass)); -``` - -### Build and run the application - -Still within the *MyApp* folder, run the application via [`dotnet run`](../tools/dotnet-run.md) and it automatically loads and uses the pre-generated serializers at run time. - -Type the following command in your console window: - -```dotnetcli -dotnet run -``` + The app automatically loads and uses the pre-generated serializers at run time. -> [!NOTE] -> [`dotnet run`](../tools/dotnet-run.md) calls [`dotnet build`](../tools/dotnet-build.md) to ensure that the build targets have been built, and then calls `dotnet ` to run the target application. + > [!TIP] + > [`dotnet run`](../tools/dotnet-run.md) calls [`dotnet build`](../tools/dotnet-build.md) to ensure that the build targets have been built, and then calls `dotnet ` to run the target application. > [!IMPORTANT] -> The commands and steps shown in this tutorial to run your application are used during development time only. Once you're ready to deploy your app, take a look at the different [deployment strategies](../deploying/index.md) for .NET Core apps and the [`dotnet publish`](../tools/dotnet-publish.md) command. +> The commands and steps shown in this tutorial to run your application are used during development time only. Once you're ready to deploy your app, take a look at the different [deployment strategies](../deploying/index.md) for .NET apps and the [`dotnet publish`](../tools/dotnet-publish.md) command. If everything succeeds, an assembly named *MyApp.XmlSerializers.dll* is generated in the output folder. Congratulations! You have just: > [!div class="checklist"] > -> - Created a .NET Core app. +> - Created a .NET console app. > - Added a reference to the Microsoft.XmlSerializer.Generator package. > - Edited your MyApp.csproj to add dependencies. > - Added a class and an XmlSerializer. -> - Built and ran the application. +> - Built and run the application. ## Further customize XML serialization assembly (optional) diff --git a/docs/core/deploying/native-aot/diagnostics.md b/docs/core/deploying/native-aot/diagnostics.md index 26dbb05e9ac41..4a4c6c966ca71 100644 --- a/docs/core/deploying/native-aot/diagnostics.md +++ b/docs/core/deploying/native-aot/diagnostics.md @@ -24,7 +24,7 @@ The following table summarizes diagnostic features supported for Native AOT depl ## Observability and telemetry -As of .NET 8, the Native AOT runtime supports [EventPipe](../../diagnostics/eventpipe.md), which is the base layer used by many logging and tracing libraries. You can interface with EventPipe directly through APIs like `EventSource.WriteEvent` or you can use libraries built on top, like [OpenTelemetry](../../diagnostics/observability-with-otel.md). EventPipe support also allows .NET diagnostic tools like [dotnet-trace](../../diagnostics/dotnet-trace.md), [dotnet-counter](../../diagnostics/dotnet-counters.md), and [dotnet-monitor](../../diagnostics/dotnet-monitor.md) to work seamlessly with Native AOT or CoreCLR applications. EventPipe is an optional component in Native AOT. To include EventPipe support, set the `EventSourceSupport` MSBuild property to `true`. +As of .NET 8, the Native AOT runtime supports [EventPipe](../../diagnostics/eventpipe.md), which is the base layer used by many logging and tracing libraries. You can interface with EventPipe directly through APIs like `EventSource.WriteEvent` or you can use libraries built on top, like [OpenTelemetry](../../diagnostics/observability-with-otel.md). EventPipe support also allows .NET diagnostic tools like [dotnet-trace](../../diagnostics/dotnet-trace.md), [dotnet-counters](../../diagnostics/dotnet-counters.md), and [dotnet-monitor](../../diagnostics/dotnet-monitor.md) to work seamlessly with Native AOT or CoreCLR applications. EventPipe is an optional component in Native AOT. To include EventPipe support, set the `EventSourceSupport` MSBuild property to `true`. ```xml diff --git a/docs/core/deploying/trimming/trim-warnings/il2001.md b/docs/core/deploying/trimming/trim-warnings/il2001.md index 536989f6c820e..909f24a945b08 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2001.md +++ b/docs/core/deploying/trimming/trim-warnings/il2001.md @@ -14,7 +14,7 @@ An XML descriptor file is trying to preserve fields on a type with no fields. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md#descriptor-format) +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to direct the IL trimmer to always keep certain members in an assembly, regardless of whether the trimmer can find references to them. However, trying to preserve members that cannot be found will trigger a warning. diff --git a/docs/core/deploying/trimming/trim-warnings/il2002.md b/docs/core/deploying/trimming/trim-warnings/il2002.md index 1f22514f671e0..3396121b9a376 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2002.md +++ b/docs/core/deploying/trimming/trim-warnings/il2002.md @@ -14,7 +14,7 @@ An XML descriptor file is trying to preserve methods on a type with no methods. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md#descriptor-format) +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to direct the IL trimmer to always keep certain members in an assembly, regardless of whether the trimmer can find references to them. However, trying to preserve members that cannot be found will trigger a warning. diff --git a/docs/core/deploying/trimming/trim-warnings/il2007.md b/docs/core/deploying/trimming/trim-warnings/il2007.md index 561f7ae95063c..e85bcf2635528 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2007.md +++ b/docs/core/deploying/trimming/trim-warnings/il2007.md @@ -14,7 +14,7 @@ An assembly specified in a descriptor file could not be resolved. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. The assembly specified in the descriptor file by its full name could not be found in any of the assemblies seen by the trimmer. diff --git a/docs/core/deploying/trimming/trim-warnings/il2008.md b/docs/core/deploying/trimming/trim-warnings/il2008.md index e6a252c39635b..86cd7143e6980 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2008.md +++ b/docs/core/deploying/trimming/trim-warnings/il2008.md @@ -14,7 +14,7 @@ A type specified in a descriptor file could not be resolved. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. diff --git a/docs/core/deploying/trimming/trim-warnings/il2009.md b/docs/core/deploying/trimming/trim-warnings/il2009.md index 053f045562924..be2d43b229926 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2009.md +++ b/docs/core/deploying/trimming/trim-warnings/il2009.md @@ -14,7 +14,7 @@ A method specified on a type in a descriptor file could not be resolved. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. diff --git a/docs/core/deploying/trimming/trim-warnings/il2010.md b/docs/core/deploying/trimming/trim-warnings/il2010.md index 41af6c68e3326..d40f1753fb3f3 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2010.md +++ b/docs/core/deploying/trimming/trim-warnings/il2010.md @@ -15,7 +15,7 @@ value of a built-in type or match the return type of the method. ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with a `throw` statement or to return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2011.md b/docs/core/deploying/trimming/trim-warnings/il2011.md index 7cbf949e45772..217837bd8bb59 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2011.md +++ b/docs/core/deploying/trimming/trim-warnings/il2011.md @@ -14,7 +14,7 @@ The action value passed to the `body` argument of a `method` element in a substi ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with a `throw` statement or to return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2012.md b/docs/core/deploying/trimming/trim-warnings/il2012.md index 4a476239cd1de..6f27b91095257 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2012.md +++ b/docs/core/deploying/trimming/trim-warnings/il2012.md @@ -14,7 +14,7 @@ A field specified for substitution in a substitution file could not be found. ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2013.md b/docs/core/deploying/trimming/trim-warnings/il2013.md index 36be363bcc812..d17ffaa5d347c 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2013.md +++ b/docs/core/deploying/trimming/trim-warnings/il2013.md @@ -14,7 +14,7 @@ A field specified for substitution in a substitution file is non-static or const ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2014.md b/docs/core/deploying/trimming/trim-warnings/il2014.md index f9df5089e6c2c..5225308e6343a 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2014.md +++ b/docs/core/deploying/trimming/trim-warnings/il2014.md @@ -15,7 +15,7 @@ substituted for was given. ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2015.md b/docs/core/deploying/trimming/trim-warnings/il2015.md index a6ba8aec8d84e..8fcff0a32903e 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2015.md +++ b/docs/core/deploying/trimming/trim-warnings/il2015.md @@ -15,7 +15,7 @@ value of a built-in type or does not match the type of the field. ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2016.md b/docs/core/deploying/trimming/trim-warnings/il2016.md index ab45f38133024..f5d356d616a0e 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2016.md +++ b/docs/core/deploying/trimming/trim-warnings/il2016.md @@ -14,7 +14,7 @@ Could not find event on type. ## Rule description -An event specified in an [xml file for the trimmer](https://github.com/mono/linker/blob/main/docs/data-formats.md) +An event specified in an [XML file for the trimmer](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md) file could not be found in the type matching the `fullname` argument that was passed to the parent of the `event` element. diff --git a/docs/core/deploying/trimming/trim-warnings/il2017.md b/docs/core/deploying/trimming/trim-warnings/il2017.md index 67631ef06bc30..4a3c866a72bc5 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2017.md +++ b/docs/core/deploying/trimming/trim-warnings/il2017.md @@ -14,7 +14,7 @@ Could not find property on type. ## Rule description -A property specified in an [xml file for the trimmer](https://github.com/mono/linker/blob/main/docs/data-formats.md) +A property specified in an [XML file for the trimmer](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md) file could not be found in the type matching the `fullname` argument that was passed to the parent of the `property` element. diff --git a/docs/core/deploying/trimming/trim-warnings/il2018.md b/docs/core/deploying/trimming/trim-warnings/il2018.md index c7a636339ea6d..fc7be4fd9857d 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2018.md +++ b/docs/core/deploying/trimming/trim-warnings/il2018.md @@ -14,7 +14,7 @@ A `get` accessor specified in a descriptor file could not be found. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. diff --git a/docs/core/deploying/trimming/trim-warnings/il2019.md b/docs/core/deploying/trimming/trim-warnings/il2019.md index 3fa0a0189d3a4..2b699d9bc704e 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2019.md +++ b/docs/core/deploying/trimming/trim-warnings/il2019.md @@ -14,7 +14,7 @@ A `set` accessor specified in a descriptor file could not be found. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. diff --git a/docs/core/deploying/trimming/trim-warnings/il2022.md b/docs/core/deploying/trimming/trim-warnings/il2022.md index 8439d8e875d5a..d776dd979070c 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2022.md +++ b/docs/core/deploying/trimming/trim-warnings/il2022.md @@ -15,7 +15,7 @@ could not be found. ## Rule description -[Custom attribute annotation files](https://github.com/mono/linker/blob/main/docs/data-formats.md#custom-attributes-annotations-format) +[Custom attribute annotation files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#custom-attributes-annotations-format) are used to instruct the trimmer to behave as if the specified item has a given attribute. Attribute annotations can only be used to add attributes that have an effect on the trimmer behavior; all other attributes are ignored. Attributes added via diff --git a/docs/core/deploying/trimming/trim-warnings/il2023.md b/docs/core/deploying/trimming/trim-warnings/il2023.md index 6fd240add4bb8..74b39db232ead 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2023.md +++ b/docs/core/deploying/trimming/trim-warnings/il2023.md @@ -15,7 +15,7 @@ element when putting an attribute on the return parameter of a method. ## Rule description -[Custom attribute annotation files](https://github.com/mono/linker/blob/main/docs/data-formats.md#custom-attributes-annotations-format) +[Custom attribute annotation files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#custom-attributes-annotations-format) are used to instruct the trimmer to behave as if the specified item has a given attribute. Attribute annotations can only be used to add attributes that have effect on the trimmer behavior. All other attributes are ignored. Attributes added via diff --git a/docs/core/deploying/trimming/trim-warnings/il2024.md b/docs/core/deploying/trimming/trim-warnings/il2024.md index ad8fce053bb31..8ce1ef5ce79a2 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2024.md +++ b/docs/core/deploying/trimming/trim-warnings/il2024.md @@ -15,7 +15,7 @@ specified for each method parameter. ## Rule description -[Custom attribute annotation files](https://github.com/mono/linker/blob/main/docs/data-formats.md#custom-attributes-annotations-format) +[Custom attribute annotation files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#custom-attributes-annotations-format) are used to instruct the trimmer to behave as if the specified item has a given attribute. Attribute annotations can only be used to add attributes which have effect on the trimmer behavior, all other attributes will be ignored. Attributes added via diff --git a/docs/core/deploying/trimming/trim-warnings/il2025.md b/docs/core/deploying/trimming/trim-warnings/il2025.md index c3539f4d8c71d..b33994cc448bd 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2025.md +++ b/docs/core/deploying/trimming/trim-warnings/il2025.md @@ -14,7 +14,7 @@ A member on a type is marked for preservation more than once in a descriptor fil ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. diff --git a/docs/core/deploying/trimming/trim-warnings/il2029.md b/docs/core/deploying/trimming/trim-warnings/il2029.md index 39f5769d25514..900077264803a 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2029.md +++ b/docs/core/deploying/trimming/trim-warnings/il2029.md @@ -15,7 +15,7 @@ argument `fullname` or its value is an empty string. ## Rule description -[Custom attribute annotation files](https://github.com/mono/linker/blob/main/docs/data-formats.md#custom-attributes-annotations-format) +[Custom attribute annotation files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#custom-attributes-annotations-format) are used to instruct the trimmer to behave as if the specified item has a given attribute. Attribute annotations can only be used to add attributes that have effect on the trimmer behavior. All other attributes are ignored. Attributes added via diff --git a/docs/core/deploying/trimming/trim-warnings/il2030.md b/docs/core/deploying/trimming/trim-warnings/il2030.md index 00fa26b225038..52fb981b0629e 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2030.md +++ b/docs/core/deploying/trimming/trim-warnings/il2030.md @@ -15,7 +15,7 @@ custom attribute annotations file. ## Rule description -[Custom attribute annotation files](https://github.com/mono/linker/blob/main/docs/data-formats.md#custom-attributes-annotations-format) +[Custom attribute annotation files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#custom-attributes-annotations-format) are used to instruct the trimmer to behave as if the specified item has a given attribute. Attribute annotations can only be used to add attributes which have effect on the trimmer behavior, all other attributes will be ignored. Attributes added via diff --git a/docs/core/deploying/trimming/trim-warnings/il2031.md b/docs/core/deploying/trimming/trim-warnings/il2031.md index 0d254826eb7f3..837371d64fb03 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2031.md +++ b/docs/core/deploying/trimming/trim-warnings/il2031.md @@ -15,7 +15,7 @@ argument of an attribute element in a custom attribute annotations file. ## Rule description -[Custom attribute annotation files](https://github.com/mono/linker/blob/main/docs/data-formats.md#custom-attributes-annotations-format) +[Custom attribute annotation files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#custom-attributes-annotations-format) are used to instruct the trimmer to behave as if the specified item has a given attribute. Attribute annotations can only be used to add attributes which have effect on the trimmer behavior, all other attributes will be ignored. Attributes added via diff --git a/docs/core/deploying/trimming/trim-warnings/il2038.md b/docs/core/deploying/trimming/trim-warnings/il2038.md index 7510b3b029fb8..b698ac42cd0b6 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2038.md +++ b/docs/core/deploying/trimming/trim-warnings/il2038.md @@ -14,7 +14,7 @@ A `resource` element in a substitution file does not specify the required `name` ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2039.md b/docs/core/deploying/trimming/trim-warnings/il2039.md index 7b32b47dec6ed..55c37942cc565 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2039.md +++ b/docs/core/deploying/trimming/trim-warnings/il2039.md @@ -14,7 +14,7 @@ The value passed to the `action` argument of a `resource` element in a substitut ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2040.md b/docs/core/deploying/trimming/trim-warnings/il2040.md index d0bb119018ba3..db091c16fd012 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2040.md +++ b/docs/core/deploying/trimming/trim-warnings/il2040.md @@ -15,7 +15,7 @@ found in the specified assembly. ## Rule description -[Substitution files](https://github.com/mono/linker/blob/main/docs/data-formats.md#substitution-format) +[Substitution files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#substitution-format) are used to instruct the trimmer to replace specific method bodies with either a throw or return constant statements. diff --git a/docs/core/deploying/trimming/trim-warnings/il2044.md b/docs/core/deploying/trimming/trim-warnings/il2044.md index ec53022cfc685..cf34618aaadac 100644 --- a/docs/core/deploying/trimming/trim-warnings/il2044.md +++ b/docs/core/deploying/trimming/trim-warnings/il2044.md @@ -14,7 +14,7 @@ The descriptor file specified a namespace that has no types in it. ## Rule description -[Descriptor files](https://github.com/mono/linker/blob/main/docs/data-formats.md) are +[Descriptor files](https://github.com/dotnet/runtime/blob/main/docs/tools/illink/data-formats.md#descriptor-format) are used to instruct the trimmer to always keep certain items in an assembly, regardless of whether the trimmer could find any references to them. diff --git a/docs/core/diagnostics/built-in-metrics-aspnetcore.md b/docs/core/diagnostics/built-in-metrics-aspnetcore.md index 8b293fd6de8d4..f435f93499a40 100644 --- a/docs/core/diagnostics/built-in-metrics-aspnetcore.md +++ b/docs/core/diagnostics/built-in-metrics-aspnetcore.md @@ -35,7 +35,7 @@ The `Microsoft.AspNetCore.Hosting` metrics report high-level information about H | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If one was sent. | | `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. | +| `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: diff --git a/docs/core/diagnostics/compare-metric-apis.md b/docs/core/diagnostics/compare-metric-apis.md index 50044cfbca558..5b80d1d33611d 100644 --- a/docs/core/diagnostics/compare-metric-apis.md +++ b/docs/core/diagnostics/compare-metric-apis.md @@ -58,7 +58,7 @@ For more information, see [Performance counters in .NET Framework](../../framewo The [EventCounters](event-counters.md) API came next after `PerformanceCounters`. This API aimed to provide a uniform cross-platform experience. The APIs are available by targeting .NET Core 3.1+, and a small subset is available on .NET Framework 4.7.1 -and above. These APIs are fully supported and are actively used by key .NET libraries, but they +and later. These APIs are fully supported and are actively used by key .NET libraries, but they have less functionality than the newer APIs. EventCounters are able to report rates of change and averages, but do not support histograms and percentiles. There is also no support for multi-dimensional metrics. Custom tooling is possible via the API, though it is not strongly typed, only gives diff --git a/docs/core/diagnostics/debug-deadlock.md b/docs/core/diagnostics/debug-deadlock.md index a4e6fff18e79e..a608fd82f9cf5 100644 --- a/docs/core/diagnostics/debug-deadlock.md +++ b/docs/core/diagnostics/debug-deadlock.md @@ -18,7 +18,7 @@ In this tutorial, you will: > - Investigate an app that has stopped responding > - Generate a core dump file > - Analyze process threads in the dump file -> - Analyze callstacks and sync blocks +> - Analyze call stacks and sync blocks > - Diagnose and solve a deadlock ## Prerequisites diff --git a/docs/core/diagnostics/dotnet-dump.md b/docs/core/diagnostics/dotnet-dump.md index 84570b91e4fd3..eed83a6307086 100644 --- a/docs/core/diagnostics/dotnet-dump.md +++ b/docs/core/diagnostics/dotnet-dump.md @@ -169,7 +169,7 @@ dotnet-dump analyze [-h|--help] [-c|--command] | `dumpgcdata` | Displays information about the GC data. | | `dumpgen` | Displays heap content for the specified generation. | | `dumpheap` | Displays info about the garbage-collected heap and collection statistics about objects. | -| `dumpil` | Displays the Microsoft intermediate language (MSIL) that's associated with a managed method. | +| `dumpil` | Displays the common intermediate language (CIL) that's associated with a managed method. | | `dumplog` | Writes the contents of an in-memory stress log to the specified file. | | `dumpmd` | Displays information about the `MethodDesc` structure at the specified address. | | `dumpmodule` | Displays information about the module at the specified address. | diff --git a/docs/core/diagnostics/event-counters.md b/docs/core/diagnostics/event-counters.md index 13a9218878f07..1a0adda81e953 100644 --- a/docs/core/diagnostics/event-counters.md +++ b/docs/core/diagnostics/event-counters.md @@ -39,7 +39,7 @@ An event listener specifies how long measurement intervals are. At the end of ea ## Implement an EventSource -The following code implements a sample exposed as the named `"Sample.EventCounter.Minimal"` provider. This source contains an representing request-processing time. Such a counter has a name (that is, its unique ID in the source) and a display name, both used by listener tools such as [dotnet-counter](dotnet-counters.md). +The following code implements a sample exposed as the named `"Sample.EventCounter.Minimal"` provider. This source contains an representing request-processing time. Such a counter has a name (that is, its unique ID in the source) and a display name, both used by listener tools such as [dotnet-counters](dotnet-counters.md). :::code language="csharp" source="snippets/EventCounters/MinimalEventCounterSource.cs"::: diff --git a/docs/core/diagnostics/snippets/Metrics/prometheus.yml b/docs/core/diagnostics/snippets/Metrics/prometheus.yml index c865a3953bf37..032541ee72a6d 100644 --- a/docs/core/diagnostics/snippets/Metrics/prometheus.yml +++ b/docs/core/diagnostics/snippets/Metrics/prometheus.yml @@ -1,4 +1,4 @@ - my global config +# my global config global: scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute. evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute. diff --git a/docs/core/diagnostics/sos-debugging-extension.md b/docs/core/diagnostics/sos-debugging-extension.md index 7c1cc184b1840..3f85bdcca865f 100644 --- a/docs/core/diagnostics/sos-debugging-extension.md +++ b/docs/core/diagnostics/sos-debugging-extension.md @@ -41,7 +41,7 @@ The following table of commands is also available under **Help** or **soshelp**. | **DumpClass** \<*EEClass address*> | Displays information about the `EEClass` structure associated with a type.

The **DumpClass** command displays static field values but does not display nonstatic field values.

Use the **DumpMT**, **DumpObj**, **Name2EE**, or **Token2EE** command to get an `EEClass` structure address. | | **DumpDomain** [\<*domain address*>] | Enumerates each object that's loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process. Since .NET (Core) only has one , **DumpDomain** only returns one object. | | **DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]] | Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes.

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes.

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address. | -| **DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*> | Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.

Dynamic MSIL is emitted differently than MSIL that's loaded from an assembly. Dynamic MSIL refers to objects in a managed object array rather than to metadata tokens. | +| **DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*> | Displays the common intermediate language (CIL) that's associated with a managed method.

Dynamic CIL is emitted differently than CIL that's loaded from an assembly. Dynamic CIL refers to objects in a managed object array rather than to metadata tokens. | | **DumpLog** [**-addr** \<*addressOfStressLog*>] [<*Filename*>] | Writes the contents of an in-memory stress log to the specified file. If you do not specify a name, this command creates a file called StressLog.txt in the current directory.

The in-memory stress log helps you diagnose stress failures without using locks or I/O. To enable the stress log, set the following registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\.NETFramework:

(DWORD) StressLog = 1

(DWORD) LogFacility = 0xffffffff

(DWORD) StressLogSize = 65536

The optional `-addr` option lets you specify a stress log other than the default log. | | **DumpMD** \<*MethodDesc address*> | Displays information about a `MethodDesc` structure at the specified address.

You can use the **IP2MD** command to get the `MethodDesc` structure address from a managed function. | | **DumpMT** [**-MD**] \<*MethodTable address*> | Displays information about a method table at the specified address. Specifying the **-MD** option displays a list of all methods defined with the object.

Each managed object contains a method table pointer. | @@ -135,7 +135,7 @@ By default you can reach all the SOS commands by entering: `sos [command_name]`. | `dumpgcdata` | Displays information about the GC data. | | `dumpgen` | Displays heap content for the specified generation. | | `dumpheap` | Displays info about the garbage-collected heap and collection statistics about objects. | -| `dumpil` | Displays the Microsoft intermediate language (MSIL) that's associated with a managed method. | +| `dumpil` | Displays the common intermediate language (CIL) that's associated with a managed method. | | `dumplog` | Writes the contents of an in-memory stress log to the specified file. | | `dumpmd` | Displays information about the `MethodDesc` structure at the specified address. | | `dumpmodule` | Displays information about the module at the specified address. | diff --git a/docs/core/diagnostics/symbols.md b/docs/core/diagnostics/symbols.md index edf11a470f642..1dc2bd156991d 100644 --- a/docs/core/diagnostics/symbols.md +++ b/docs/core/diagnostics/symbols.md @@ -6,41 +6,41 @@ ms.date: 02/08/2021 # Symbols -Symbols are useful for debugging and other diagnostic tools. The contents of symbol files vary between languages, compilers, and platforms. At a very high level symbols are a mapping between the source code and the binary produced by the compiler. These mappings are used by tools like [Visual Studio](/visualstudio/debugger/what-is-debugging) and [Visual Studio Code](https://code.visualstudio.com/Docs/editor/debugging) to resolve source line number information or local variable names. +Symbols are useful for debugging and other diagnostic tools. The contents of symbol files vary between languages, compilers, and platforms. At a high level, symbols are a mapping between the source code and the binary produced by the compiler. These mappings are used by tools like [Visual Studio](/visualstudio/debugger/what-is-debugging) and [Visual Studio Code](https://code.visualstudio.com/Docs/editor/debugging) to resolve source line number information or local variable names. The [Windows documentation on symbols](/windows/win32/dxtecharts/debugging-with-symbols) contain more detailed information on symbols for Windows, although many of the concepts apply to other platforms as well. -## Learn about .NET's Portable PDB format +## Learn about .NET's portable PDB format -.NET Core introduces a new symbol file (PDB) format - the portable PDB. Unlike traditional PDBs which are Windows-only, portable PDBs can be created and read on all platforms. +.NET Core introduced a new symbol file (PDB) format - the portable PDB. Unlike traditional PDBs, which are Windows-only, portable PDBs can be created and read on all platforms. ### What is a PDB? A PDB file is an auxiliary file produced by a compiler to provide other tools, especially debuggers, information about what is in the main executable file and how it was produced. For example, a debugger reads a PDB to map foo.cs line 12 to the right executable location so that it can set a breakpoint. The Windows PDB format has been around a long time, and it evolved from other native debugging symbol formats which were even older. It started out its life as a format for native (C/C++) programs. For the first release of the .NET Framework, the Windows PDB format was extended to support .NET. -The Portable PDB format was introduced in .NET Core, and it's used by default when targeting .NET Core and .NET 5+. When targeting .NET Framework, you can enable Portable PDB symbols by specifying `portable` in your project file. The Portable PDB format is based on ECMA-335 metadata format. For more information, see [Portable PDB v1.0: Format Specification](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md). Diagnostic tools can use the library to read Portable PDB files (for an example, see ). +The Portable PDB format was introduced in .NET Core, and it's used by default when targeting .NET. When targeting .NET Framework, you can enable portable PDB symbols by specifying `portable` in your project file. The portable PDB format is based on ECMA-335 metadata format. For more information, see [Portable PDB v1.0: Format Specification](https://github.com/dotnet/runtime/blob/main/docs/design/specs/PortablePdb-Metadata.md). Diagnostic tools can use the library to read portable PDB files (for an example, see ). ## Use the correct PDB format for your scenario -Neither portable PDBs nor Windows PDBs are supported everywhere, so you need to consider where your project will want to be used and debugged to decide which format to use. If you have a project that you want to be able to use and debug in both formats, you can use different build configurations and build the project twice to support both types of consumer. +Neither portable PDBs nor Windows PDBs are supported everywhere. To decide which format to use, consider where your project will be used and debugged. If you have a project that you want to be able to use and debug in both formats, you can use different build configurations and build the project twice to support both types of consumer. -### Support for Portable PDBs +### Support for portable PDBs -Portable PDBs can be read on any operating systems and is the recommended symbol format for managed code, but there are a number of legacy tools and applications where they aren't supported: +A portable PDB can be read on any operating system and is the recommended symbol format for managed code. However, there are a number of legacy tools and applications where they aren't supported: * Applications targeting .NET Framework 4.7.1 or earlier: printing stack traces with mappings back to line numbers (such as in an ASP.NET error page). The name of methods is unaffected, only the source file names and line numbers are unsupported. -* Using .NET decompilers such as ildasm or .NET reflector and expecting to see source line mappings or local parameter names. +* When you use .NET decompilers such as ildasm or .NET reflector, you won't see source line mappings or local parameter names. -* The latest versions of [DIA](/visualstudio/debugger/debug-interface-access/debug-interface-access-sdk) and tools using it for reading symbols, such as WinDBG support Portable PDBs, but older versions do not. +* The latest versions of [DIA](/visualstudio/debugger/debug-interface-access/debug-interface-access-sdk) and tools that use DIA for reading symbols, such as WinDBG, support portable PDBs, but older versions don't. -* There may be older versions of profilers that do not support portable PDBs. +* There might be older versions of profilers that don't support portable PDBs. -To use portable PDBs on tools that do not support them, you can try using [Pdb2Pdb](https://github.com/dotnet/symreader-converter#pdb2pdb) which converts between Portable PDBs and Windows PDBs. +To use portable PDBs on tools that do not support them, you can use [Pdb2Pdb](https://github.com/dotnet/symreader-converter#pdb2pdb), which converts between portable PDBs and Windows PDBs. ### Support for Windows PDBs -Windows PDBs can only be written or read on Windows. Using Windows PDBs for managed code is obsolete and is only needed for legacy tools. It is recommended that you use portable PDBs instead of Windows PDBs as some newer compiler features that are implemented for only portable PDBs. +Windows PDBs can only be written or read on Windows. Using Windows PDBs for managed code is obsolete and is only needed for legacy tools. It is recommended that you use portable PDBs instead of Windows PDBs, as some newer compiler features are implemented only for portable PDBs. ## See also diff --git a/docs/core/extensions/globalization-icu.md b/docs/core/extensions/globalization-icu.md index e52101f5503a7..57f7bce20cdc4 100644 --- a/docs/core/extensions/globalization-icu.md +++ b/docs/core/extensions/globalization-icu.md @@ -61,7 +61,7 @@ Console.WriteLine($"{greeting.IndexOf("\0", StringComparison.Ordinal)}"); ``` - In .NET Core 3.1 and earlier versions on Windows, the snippet prints `3` on each of the three lines. -- For .NET 5 and subsequent versions running on the Windows versions listed in the [ICU on Windows](#icu-on-windows) section table, the snippet prints `0`, `0`, and `3` (for the ordinal search). +- For .NET 5 and later versions running on the Windows versions listed in the [ICU on Windows](#icu-on-windows) section table, the snippet prints `0`, `0`, and `3` (for the ordinal search). By default, performs a culture-aware linguistic search. ICU considers the null character `\0` to be a *zero-weight character*, and thus the character isn't found in the string when using a linguistic search on .NET 5 and later. However, NLS doesn't consider the null character `\0` to be a zero-weight character, and a linguistic search on .NET Core 3.1 and earlier locates the character at position 3. An ordinal search finds the character at position 3 on all .NET versions. diff --git a/docs/core/extensions/high-performance-logging.md b/docs/core/extensions/high-performance-logging.md index 4337223080856..d4543ca19f3ad 100644 --- a/docs/core/extensions/high-performance-logging.md +++ b/docs/core/extensions/high-performance-logging.md @@ -3,20 +3,20 @@ title: High-performance logging author: IEvangelist description: Learn how to use LoggerMessage to create cacheable delegates that require fewer object allocations for high-performance logging scenarios. ms.author: dapine -ms.date: 03/13/2023 +ms.date: 04/11/2024 --- # High-performance logging in .NET The class exposes functionality to create cacheable delegates that require fewer object allocations and reduced computational overhead compared to [logger extension methods](xref:Microsoft.Extensions.Logging.LoggerExtensions), such as and . For high-performance logging scenarios, use the pattern. - provides the following performance advantages over Logger extension methods: + provides the following performance advantages over logger extension methods: - Logger extension methods require "boxing" (converting) value types, such as `int`, into `object`. The pattern avoids boxing by using static fields and extension methods with strongly typed parameters. - Logger extension methods must parse the message template (named format string) every time a log message is written. only requires parsing a template once when the message is defined. > [!IMPORTANT] -> Instead of using the [LoggerMessage class](xref:Microsoft.Extensions.Logging.LoggerMessage) to create high-performance logs, you can use the [LoggerMessage attribute](xref:Microsoft.Extensions.Logging.LoggerMessageAttribute) in .NET 6.0. The `LoggerMessageAttribute` provides source-generation logging support designed to deliver a highly usable and highly performant logging solution for modern .NET applications. For more information, see [Compile-time logging source generation (.NET Fundamentals)](./logger-message-generator.md). +> Instead of using the [LoggerMessage class](xref:Microsoft.Extensions.Logging.LoggerMessage) to create high-performance logs, you can use the [LoggerMessage attribute](xref:Microsoft.Extensions.Logging.LoggerMessageAttribute) in .NET 6 and later versions. The `LoggerMessageAttribute` provides source-generation logging support designed to deliver a highly usable and highly performant logging solution for modern .NET applications. For more information, see [Compile-time logging source generation (.NET Fundamentals)](./logger-message-generator.md). The sample app demonstrates features with a priority queue processing worker service. The app processes work items in priority order. As these operations occur, log messages are generated using the pattern. @@ -52,7 +52,7 @@ Structured logging stores may use the event name when it's supplied with the eve The is invoked through a strongly typed extension method. The `PriorityItemProcessed` method logs a message every time a work item is processed. `FailedToProcessWorkItem` is called if and when an exception occurs: -:::code language="csharp" source="snippets/logging/worker-service-options/Worker.cs" range="9-30" highlight="15-18"::: +:::code language="csharp" source="snippets/logging/worker-service-options/Worker.cs" range="9-33" highlight="17-20"::: Inspect the app's console output: @@ -78,7 +78,7 @@ The static extension method for logging that a work item is being processed, `Pr In the worker service's `ExecuteAsync` method, `PriorityItemProcessed` is called to log the message: -:::code language="csharp" source="snippets/logging/worker-service-options/Worker.cs" range="9-30" highlight="12"::: +:::code language="csharp" source="snippets/logging/worker-service-options/Worker.cs" range="9-33" highlight="14"::: Inspect the app's console output: @@ -89,7 +89,7 @@ info: WorkerServiceOptions.Example.Worker[1] ## Define logger message scope -The [DefineScope(string)](xref:Microsoft.Extensions.Logging.LoggerMessage.DefineScope%2A) method creates a delegate for defining a [log scope](logging.md#log-scopes). overloads permit passing up to three type parameters to a named format string (template). +The [DefineScope(string)](xref:Microsoft.Extensions.Logging.LoggerMessage.DefineScope%2A) method creates a delegate for defining a [log scope](logging.md#log-scopes). overloads permit passing up to six type parameters to a named format string (template). As is the case with the method, the string provided to the method is a template and not an interpolated string. Placeholders are filled in the order that the types are specified. Placeholder names in the template should be descriptive and consistent across templates. They serve as property names within structured log data. We recommend [Pascal casing](../../standard/design-guidelines/capitalization-conventions.md) for placeholder names. For example, `{Item}`, `{DateTime}`. @@ -97,11 +97,11 @@ Define a [log scope](logging.md#log-scopes) to apply to a series of log messages :::code language="json" source="snippets/logging/worker-service-options/appsettings.json" highlight="3-5"::: -To create a log scope, add a field to hold a delegate for the scope. The sample app creates a field called `_processingWorkScope` (*Internal/LoggerExtensions.cs*): +To create a log scope, add a field to hold a delegate for the scope. The sample app creates a field named `s_processingWorkScope` (*Internal/LoggerExtensions.cs*): :::code language="csharp" source="snippets/logging/worker-service-options/Extensions/LoggerExtensions.cs" id="ProcessingWorkField"::: -Use to create the delegate. Up to three types can be specified for use as template arguments when the delegate is invoked. The sample app uses a message template that includes the date time in which processing started: +Use to create the delegate. Up to six types can be specified for use as template arguments when the delegate is invoked. The sample app uses a message template that includes the date time in which processing started: :::code language="csharp" source="snippets/logging/worker-service-options/Extensions/LoggerExtensions.cs" id="ProcessingWorkAssignment"::: @@ -111,38 +111,40 @@ Provide a static extension method for the log message. Include any type paramete The scope wraps the logging extension calls in a [using](../../csharp/language-reference/statements/using.md) block: -:::code language="csharp" source="snippets/logging/worker-service-options/Worker.cs" range="9-30" highlight="4"::: +:::code language="csharp" source="snippets/logging/worker-service-options/Worker.cs" range="9-33" highlight="4"::: Inspect the log messages in the app's console output. The following result shows priority ordering of log messages with the log scope message included: ```console info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-Extreme (f5090ede-a337-4041-b914-f6bc0db5ae64): 'Verify communications' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-Extreme (7d153ef9-8894-4282-836a-8e5e38319fb3): 'Verify communications' info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down. info: Microsoft.Hosting.Lifetime[0] Hosting environment: Development info: Microsoft.Hosting.Lifetime[0] - Content root path: ..\worker-service-options + Content root path: D:\source\repos\dotnet-docs\docs\core\extensions\snippets\logging\worker-service-options info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-High (496d440f-2007-4391-b179-09d75ab52373): 'Validate collection' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-High (dbad6558-60cd-4eb1-8531-231e90081f62): 'Validate collection' info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-Medium (dea9e3f4-d7df-46d2-b7cd-5e0232eb98a5): 'Propagate selections' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-Medium (1eabe213-dc64-4e3a-9920-f67fe1dfb0f6): 'Propagate selections' info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-Medium (089d7f0d-da72-4b55-92fe-57b147838056): 'Enter pooling [contention]' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-Medium (1142688d-d4dc-4f78-95c5-04ec01cbfac7): 'Enter pooling [contention]' info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-Low (6e68c4be-089f-4450-9080-1ea63fcbb686): 'Health check network' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-Low (e85e0c4d-0840-476e-b8b0-22505c08e913): 'Health check network' info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-Deferred (6f324134-6bb6-455f-81d4-553ab307c421): 'Ping weather service' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-Deferred (07571363-d559-4e72-bc33-cd8398348786): 'Ping weather service' info: WorkerServiceOptions.Example.Worker[1] - => Processing work, started at: 09/25/2020 14:30:45 - Processing priority item: Priority-Deferred (37bf736c-7a26-4a2a-9e56-e89bcf3b8f35): 'Set process state' + => Processing scope, started at: 04/11/2024 11:27:52 + Processing priority item: Priority-Deferred (2bf74f2f-0198-4831-8138-03368e60bd6b): 'Set process state' +info: Microsoft.Hosting.Lifetime[0] + Application is shutting down... ``` ## Log level guarded optimizations diff --git a/docs/core/extensions/logging.md b/docs/core/extensions/logging.md index 877fd70e5a544..ca6b603a8b460 100644 --- a/docs/core/extensions/logging.md +++ b/docs/core/extensions/logging.md @@ -328,7 +328,7 @@ The following table lists the value In the previous table, the `LogLevel` is listed from lowest to highest severity. -The [Log](xref:Microsoft.Extensions.Logging.LoggerExtensions) method's first parameter, , indicates the severity of the log. Rather than calling `Log(LogLevel, ...)`, most developers call the [Log{LogLevel}](xref:Microsoft.Extensions.Logging.LoggerExtensions) extension methods. The `Log{LogLevel}` extension methods [call the Log method and specify the LogLevel](https://github.com/dotnet/extensions/blob/release/3.1/src/Logging/Logging.Abstractions/src/LoggerExtensions.cs). For example, the following two logging calls are functionally equivalent and produce the same log: +The [Log](xref:Microsoft.Extensions.Logging.LoggerExtensions) method's first parameter, , indicates the severity of the log. Rather than calling `Log(LogLevel, ...)`, most developers call the [Log{LogLevel}](xref:Microsoft.Extensions.Logging.LoggerExtensions) extension methods. The `Log{LogLevel}` extension methods call the `Log` method and specify the `LogLevel`. For example, the following two logging calls are functionally equivalent and produce the same log: ```csharp public void LogDetails() diff --git a/docs/core/extensions/service-discovery.md b/docs/core/extensions/service-discovery.md index 078669e10c31d..aa8be70c16dae 100644 --- a/docs/core/extensions/service-discovery.md +++ b/docs/core/extensions/service-discovery.md @@ -11,7 +11,7 @@ ms.topic: overview In this article, you learn how to use the `Microsoft.Extensions.ServiceDiscovery` library. Service discovery is a way for developers to use logical names instead of physical addresses (IP address and port) to refer to external services. -## Get Started +## Get started To get started with service discovery in .NET, install the [Microsoft.Extensions.ServiceDiscovery](https://www.nuget.org/packages/Microsoft.Extensions.ServiceDiscovery) NuGet package. @@ -103,11 +103,11 @@ Here's an example demonstrating how to configure endpoints for the service named The preceding example adds two endpoints for the service named _catalog_: `https://localhost:8080`, and `"https://10.46.24.90:80"`. Each time the _catalog_ is resolved, one of these endpoints is selected. -If service discovery was added to the host using the extension method on , the configuration-based endpoint resolver can be added by calling the extension method on `IServiceCollection`. +If service discovery was added to the host using the extension method on , the configuration-based endpoint resolver can be added by calling the extension method on `IServiceCollection`. ### Configuration -The configuration resolver is configured using the class, which offers these configuration options: +The configuration resolver is configured using the class, which offers these configuration options: - **SectionName**: The name of the configuration section that contains service endpoints. It defaults to `"Services"`. @@ -122,7 +122,7 @@ builder.Services.Configure( static options => { options.SectionName = "MyServiceEndpoints"; - + // Configure the logic for applying host name metadata options.ApplyHostNameMetadata = static endpoint => { @@ -143,7 +143,7 @@ The pass-through resolver performs no external resolution and instead resolves e The pass-through provider is configured by-default when adding service discovery via the `AddServiceDiscovery` extension method. -If service discovery was added to the host using the `AddServiceDiscoveryCore` extension method on `IServiceCollection`, the pass-through provider can be added by calling the extension method on `IServiceCollection`. +If service discovery was added to the host using the `AddServiceDiscoveryCore` extension method on `IServiceCollection`, the pass-through provider can be added by calling the extension method on `IServiceCollection`. ## See also diff --git a/docs/core/extensions/snippets/logging/worker-service-options/Extensions/LoggerExtensions.cs b/docs/core/extensions/snippets/logging/worker-service-options/Extensions/LoggerExtensions.cs index 3a8e990d12262..9f4bdbdce3fd5 100644 --- a/docs/core/extensions/snippets/logging/worker-service-options/Extensions/LoggerExtensions.cs +++ b/docs/core/extensions/snippets/logging/worker-service-options/Extensions/LoggerExtensions.cs @@ -11,7 +11,7 @@ public static class LoggerExtensions #endregion #region ProcessingWorkField - private static Func s_processingWorkScope; + private static readonly Func s_processingWorkScope; #endregion static LoggerExtensions() @@ -33,7 +33,7 @@ static LoggerExtensions() #region ProcessingWorkAssignment s_processingWorkScope = LoggerMessage.DefineScope( - "Processing work, started at: {DateTime}"); + "Processing scope, started at: {DateTime}"); #endregion } diff --git a/docs/core/extensions/snippets/logging/worker-service-options/Worker.cs b/docs/core/extensions/snippets/logging/worker-service-options/Worker.cs index d51740f2c13cb..96eaf74712191 100644 --- a/docs/core/extensions/snippets/logging/worker-service-options/Worker.cs +++ b/docs/core/extensions/snippets/logging/worker-service-options/Worker.cs @@ -9,23 +9,26 @@ public sealed class Worker( protected override async Task ExecuteAsync( CancellationToken stoppingToken) { - using IDisposable? scope = logger.ProcessingWorkScope(DateTime.Now); - while (!stoppingToken.IsCancellationRequested) + using (IDisposable? scope = logger.ProcessingWorkScope(DateTime.Now)) { - WorkItem? nextItem = priorityQueue.ProcessNextHighestPriority(); - try + while (!stoppingToken.IsCancellationRequested) { - if (nextItem is not null) + try { - logger.PriorityItemProcessed(nextItem); + WorkItem? nextItem = priorityQueue.ProcessNextHighestPriority(); + + if (nextItem is not null) + { + logger.PriorityItemProcessed(nextItem); + } + } + catch (Exception ex) + { + logger.FailedToProcessWorkItem(ex); } - } - catch (Exception ex) - { - logger.FailedToProcessWorkItem(ex); - } - await Task.Delay(1_000, stoppingToken); + await Task.Delay(1_000, stoppingToken); + } } } } diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index 7e6084fb42920..a53186009e128 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -26,14 +26,14 @@ There are two types of supported releases: Long Term Support (LTS) releases and The following table lists the support status of each version of .NET (and .NET Core): | ✔️ Supported | ❌ Unsupported | -|-------------|---------------| -| 8 (LTS) | 5 | -| 7 (STS) | 3.1 | -| 6 (LTS) | 3.0 | -| | 2.1 | -| | 2.0 | -| | 1.1 | -| | 1.0 | +|--------------|-----------------| +| 8 (LTS) | 5 | +| 7 (STS) | 3.1 | +| 6 (LTS) | 3.0 | +| | 2.1 | +| | 2.0 | +| | 1.1 | +| | 1.0 | ## Install with Windows Package Manager (winget) diff --git a/docs/core/porting/net-framework-tech-unavailable.md b/docs/core/porting/net-framework-tech-unavailable.md index 3f509c6ad44e5..144894c18ab4e 100644 --- a/docs/core/porting/net-framework-tech-unavailable.md +++ b/docs/core/porting/net-framework-tech-unavailable.md @@ -24,7 +24,7 @@ For simple communication across processes, consider inter-process communication Across machines, use a network-based solution as an alternative. Preferably, use a low-overhead plain text protocol, such as HTTP. The [Kestrel web server](/aspnet/core/fundamentals/servers/kestrel), which is the web server used by ASP.NET Core, is an option here. Also, consider using for network-based, cross-machine scenarios. StreamJsonRpc, mentioned earlier, can be used for JSON or binary (via MessagePack) communication over web sockets. -For more messaging options, see [.NET Open Source Developer Projects: Messaging](https://github.com/Microsoft/dotnet/blob/master/dotnet-developer-projects.md#messaging). +For more messaging options, see [.NET Open Source Developer Projects: Messaging](https://github.com/Microsoft/dotnet/blob/main/dotnet-developer-projects.md#messaging). Because remoting is not supported, calls to `BeginInvoke()` and `EndInvoke()` on delegate objects will throw `PlatformNotSupportedException`. For more information, see [Migrating Delegate BeginInvoke Calls For .NET Core](https://devblogs.microsoft.com/dotnet/migrating-delegate-begininvoke-calls-for-net-core/). diff --git a/docs/core/project-sdk/msbuild-props-desktop.md b/docs/core/project-sdk/msbuild-props-desktop.md index d038de059db3d..0a9bc779cf6d2 100644 --- a/docs/core/project-sdk/msbuild-props-desktop.md +++ b/docs/core/project-sdk/msbuild-props-desktop.md @@ -17,14 +17,10 @@ This page is a reference for the MSBuild properties and items that you use to co ## Enable .NET Desktop SDK -To use WinForms or WPF, configure your project file. - -### .NET 5 and later versions - -Specify the following settings in the project file of your WinForms or WPF project: +To use WinForms or WPF, specify the following settings in the project file of your WinForms or WPF project: - Target the .NET SDK `Microsoft.NET.Sdk`. For more information, see [Project files](overview.md#project-files). -- Set [`TargetFramework`](msbuild-props.md#targetframework) to a Windows-specific target framework moniker, such as `net6.0-windows`. +- Set [`TargetFramework`](msbuild-props.md#targetframework) to a Windows-specific target framework moniker, such as `net8.0-windows`. - Add a UI framework property (or both, if necessary): - Set [`UseWPF`](#usewpf) to `true` to import and use WPF. - Set [`UseWindowsForms`](#usewindowsforms) to `true` to import and use WinForms. @@ -45,32 +41,6 @@ Specify the following settings in the project file of your WinForms or WPF proje ``` -### .NET Core 3.1 - -Specify the following settings in the project file of your WinForms or WPF project: - -- Target the .NET SDK `Microsoft.NET.Sdk.WindowsDesktop`. For more information, see [Project files](overview.md#project-files). -- Set [`TargetFramework`](msbuild-props.md#targetframework) to `netcoreapp3.1`. -- Add a UI framework property (or both, if necessary): - - Set [`UseWPF`](#usewpf) to `true` to import and use WPF. - - Set [`UseWindowsForms`](#usewindowsforms) to `true` to import and use WinForms. -- (Optional) Set `OutputType` to `WinExe`. This produces an app as opposed to a library. To produce a library, omit this property. - -```xml - - - - WinExe - netcoreapp3.1 - - true - - true - - - -``` - ## WPF default includes and excludes SDK projects define a set of rules to implicitly include or exclude files from the project. These rules also automatically set the file's build action. This is unlike the older non-SDK .NET Framework projects, which have no default include or exclude rules. .NET Framework projects require you to explicitly declare which files to include in the project. @@ -124,8 +94,6 @@ The `UseWPF` property controls whether or not to include references to WPF libra When this property is set to `true`, .NET 5+ projects will automatically import the [.NET Desktop SDK](#enable-net-desktop-sdk). -.NET Core 3.1 projects need to explicitly target the [.NET Desktop SDK](#enable-net-desktop-sdk) to use this property. - ### EnableDefaultApplicationDefinition The `EnableDefaultApplicationDefinition` property controls whether `ApplicationDefinition` items are implicitly included in the project. The default value is `true`. Set the `EnableDefaultApplicationDefinition` property to `false` to disable the implicit file inclusion. @@ -236,8 +204,6 @@ The `UseWindowsForms` property controls whether or not your application is built When this property is set to `true`, .NET 5+ projects will automatically import the [.NET Desktop SDK](#enable-net-desktop-sdk). -.NET Core 3.1 projects need to explicitly target the [.NET Desktop SDK](#enable-net-desktop-sdk) to use this property. - ## Shared settings - [DisableWinExeOutputInference](#disablewinexeoutputinference) diff --git a/docs/core/runtime-config/index.md b/docs/core/runtime-config/index.md index 257644451b3d5..c1e7a68248f16 100644 --- a/docs/core/runtime-config/index.md +++ b/docs/core/runtime-config/index.md @@ -9,7 +9,7 @@ ms.date: 07/23/2021 .NET 5+ (including .NET Core versions) supports the use of configuration files and environment variables to configure the behavior of .NET applications. > [!NOTE] -> The articles in this section concern configuration of the .NET Runtime itself. If you're migrating to .NET Core 3.1 or later and are looking for a replacement for the *app.config* file, or if you simply want a way to use custom configuration values in your .NET app, see the class and [Configuration in .NET](../extensions/configuration.md). +> The articles in this section concern configuration of the .NET Runtime itself. If you're migrating an app from .NET Framework to .NET and are looking for a replacement for the *app.config* file, or if you simply want a way to use custom configuration values in your .NET app, see the class and [Configuration in .NET](../extensions/configuration.md). Using these settings is an attractive option if: @@ -54,10 +54,10 @@ If you're placing the options in the output JSON file, nest them under the `runt ```json { "runtimeOptions": { - "tfm": "netcoreapp3.1", + "tfm": "net8.0", "framework": { "name": "Microsoft.NETCore.App", - "version": "3.1.0" + "version": "8.0.0" }, "configProperties": { "System.Globalization.UseNls": true, @@ -99,7 +99,7 @@ Here is an example SDK-style project file with MSBuild properties for configurin Exe - netcoreapp3.1 + net8.0 diff --git a/docs/core/runtime-config/networking.md b/docs/core/runtime-config/networking.md index ee35240648be6..e42488b144b57 100644 --- a/docs/core/runtime-config/networking.md +++ b/docs/core/runtime-config/networking.md @@ -8,12 +8,7 @@ ms.date: 11/27/2019 ## HTTP/2 protocol - Configures whether support for the HTTP/2 protocol is enabled. - -- Introduced in .NET Core 3.0. - -- .NET Core 3.0 only: If you omit this setting, support for the HTTP/2 protocol is disabled. This is equivalent to setting the value to `false`. - -- .NET Core 3.1 and .NET 5+: If you omit this setting, support for the HTTP/2 protocol is enabled. This is equivalent to setting the value to `true`. +- If you omit this setting, support for the HTTP/2 protocol is enabled. This is equivalent to setting the value to `true`. | | Setting name | Values | | - | - | - | @@ -25,9 +20,7 @@ ms.date: 11/27/2019 ## SPN creation in HttpClient (.NET 6 and later) - Impacts generation of [service principal names](/windows/win32/ad/service-principal-names) (SPN) for Kerberos and NTLM authentication when `Host` header is missing and target is not running on default port. -- .NET Core 2.x and 3.x do not include port in SPN. -- .NET Core 5.x does include port in SPN -- .NET 6 and later versions don't include the port, but the behavior is configurable. +- .NET 6 and later versions don't include the port in the SPN, but the behavior is configurable. | | Setting name | Values | | - | - | - | @@ -35,34 +28,3 @@ ms.date: 11/27/2019 | **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_USEPORTINSPN` | `1` - includes port number in SPN, for example, `HTTP/host:port`
`0` - does not include port in SPN, for example, `HTTP/host` | [!INCLUDE [runtimehostconfigurationoption](includes/runtimehostconfigurationoption.md)] - -## UseSocketsHttpHandler (.NET Core 2.1-3.1 only) - -- Configures whether uses or older HTTP protocol stacks ( on Windows and `CurlHandler`, an internal class implemented on top of [libcurl](https://curl.haxx.se/libcurl/), on Linux). - - > [!NOTE] - > You may be using high-level networking APIs instead of directly instantiating the class. This setting also affects which HTTP protocol stack is used by high-level networking APIs, including and [HttpClientFactory](/previous-versions/aspnet/hh995280(v=vs.118)). - -- If you omit this setting, uses . This is equivalent to setting the value to `true`. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Net.Http.UseSocketsHttpHandler` | `true` - enables the use of
`false` - enables the use of on Windows or [libcurl](https://curl.haxx.se/libcurl/) on Linux | -| **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` | `1` - enables the use of
`0` - enables the use of on Windows or [libcurl](https://curl.haxx.se/libcurl/) on Linux | - -> [!NOTE] -> Starting in .NET 5, the `System.Net.Http.UseSocketsHttpHandler` setting is no longer available. - -## Latin1 headers (.NET Core 3.1 only) - -- This switch allows relaxing the HTTP header validation, enabling to send ISO-8859-1 (Latin-1) encoded characters in headers. - -- If you omit this setting, an attempt to send a non-ASCII character will result in . This is equivalent to setting the value to `false`. - -| | Setting name | Values | -| - | - | - | -| **runtimeconfig.json** | `System.Net.Http.SocketsHttpHandler.AllowLatin1Headers` | `false` - disabled
`true` - enabled | -| **Environment variable** | `DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_ALLOWLATIN1HEADERS` | `0` - disabled
`1` - enabled | - -> [!NOTE] -> This option is only available in .NET Core 3.1 since version 3.1.9, and not in previous or later versions. In .NET 5 we recommend using . diff --git a/docs/core/testing/snippets/order-unit-tests/csharp/XUnit.TestProject/XUnit.Project.csproj b/docs/core/testing/snippets/order-unit-tests/csharp/XUnit.TestProject/XUnit.Project.csproj index eea43b1529c2d..9004229e898f5 100644 --- a/docs/core/testing/snippets/order-unit-tests/csharp/XUnit.TestProject/XUnit.Project.csproj +++ b/docs/core/testing/snippets/order-unit-tests/csharp/XUnit.TestProject/XUnit.Project.csproj @@ -9,8 +9,8 @@ - - + + all runtime; build; native; contentfiles; analyzers; buildtransitive diff --git a/docs/core/testing/unit-testing-fsharp-with-nunit.md b/docs/core/testing/unit-testing-fsharp-with-nunit.md index 8e359e58cb87e..5b814d6fd6922 100644 --- a/docs/core/testing/unit-testing-fsharp-with-nunit.md +++ b/docs/core/testing/unit-testing-fsharp-with-nunit.md @@ -3,12 +3,12 @@ title: Unit testing F# in .NET Core with dotnet test and NUnit description: Learn unit test concepts for F# in .NET Core through an interactive experience building a sample solution step-by-step using dotnet test and NUnit. author: rprouse ms.date: 10/04/2018 -dev_langs: +dev_langs: - "fsharp" --- -# Unit testing F# libraries in .NET Core using dotnet test and NUnit +# Unit testing F# libraries using dotnet test and NUnit -This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a pre-built solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-with-fsharp-nunit/) before you begin. For download instructions, see [Samples and Tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). +This tutorial takes you through an interactive experience building a sample solution step-by-step to learn unit testing concepts. If you prefer to follow the tutorial using a prebuilt solution, [view or download the sample code](https://github.com/dotnet/samples/tree/main/core/getting-started/unit-testing-with-fsharp-nunit/) before you begin. For download instructions, see [Samples and tutorials](../../samples-and-tutorials/index.md#view-and-download-samples). [!INCLUDE [testing an ASP.NET Core project from .NET Core](../../../includes/core-testing-note-aspnet.md)] @@ -17,7 +17,7 @@ This tutorial takes you through an interactive experience building a sample solu - [.NET 8 SDK](https://dotnet.microsoft.com/download) or later versions. - A text editor or code editor of your choice. -## Creating the source project +## Create the source project Open a shell window. Create a directory called *unit-testing-with-fsharp* to hold the solution. Inside this new directory, run the following command to create a new solution file for the class library and the test project: @@ -53,11 +53,11 @@ Change the directory back to the *unit-testing-with-fsharp* directory. Run the f dotnet sln add .\MathService\MathService.fsproj ``` -## Creating the test project +## Create the test project Next, create the *MathService.Tests* directory. The following outline shows the directory structure: -``` +```txt /unit-testing-with-fsharp unit-testing-with-fsharp.sln /MathService @@ -72,7 +72,7 @@ Make the *MathService.Tests* directory the current directory and create a new pr dotnet new nunit -lang "F#" ``` -This creates a test project that uses NUnit as the test framework. The generated template configures the test runner in the *MathServiceTests.fsproj*: +This command creates a test project that uses NUnit as the test framework. The generated template configures the test runner in the *MathServiceTests.fsproj*: ```xml @@ -92,7 +92,7 @@ You can see the entire file in the [samples repository](https://github.com/dotne You have the following final solution layout: -``` +```txt /unit-testing-with-fsharp unit-testing-with-fsharp.sln /MathService @@ -109,7 +109,7 @@ Execute the following command in the *unit-testing-with-fsharp* directory: dotnet sln add .\MathService.Tests\MathService.Tests.fsproj ``` -## Creating the first test +## Create the first test You write one failing test, make it pass, then repeat the process. Open *UnitTest1.fs* and add the following code: @@ -133,9 +133,9 @@ type TestClass () = The `[]` attribute denotes a class that contains tests. The `[]` attribute denotes a test method that is run by the test runner. From the *unit-testing-with-fsharp* directory, execute `dotnet test` to build the tests and the class library and then run the tests. The NUnit test runner contains the program entry point to run your tests. `dotnet test` starts the test runner using the unit test project you've created. -These two tests show the most basic passing and failing tests. `My test` passes, and `Fail every time` fails. Now, create a test for the `squaresOfOdds` method. The `squaresOfOdds` method returns a sequence of the squares of all odd integer values that are part of the input sequence. Rather than trying to write all of those functions at once, you can iteratively create tests that validate the functionality. Making each test pass means creating the necessary functionality for the method. +These two tests show the most basic passing and failing tests. `My test` passes, and `Fail every time` fails. Now, create a test for the `squaresOfOdds` method. The `squaresOfOdds` method returns a sequence of the squares of all odd integer values that are part of the input sequence. Rather than trying to write all of those functions at once, you can iteratively create tests that validate the functionality. To make each test pass means, you create the necessary functionality for the method. -The simplest test we can write is to call `squaresOfOdds` with all even numbers, where the result should be an empty sequence of integers. Here's that test: +The simplest test you can write is to call `squaresOfOdds` with all even numbers, where the result should be an empty sequence of integers. Here's that test: ```fsharp [] @@ -145,9 +145,9 @@ member this.TestEvenSequence() = Assert.That(actual, Is.EqualTo(expected)) ``` -Notice that the `expected` sequence has been converted to a list. The NUnit framework relies on many standard .NET types. That dependency means that your public interface and expected results support rather than . +Notice that the `expected` sequence is converted to a list. The NUnit framework relies on many standard .NET types. That dependency means that your public interface and expected results support rather than . -When you run the test, you see that your test fails. You haven't created the implementation yet. Make this test pass by writing the simplest code in the *Library.fs* class in your MathService project that works: +When you run the test, you see that your test fails. That's because you haven't created the implementation yet. Make this test pass by writing the simplest code in the *Library.fs* class in your MathService project that works: ```fsharp let squaresOfOdds xs = @@ -156,7 +156,7 @@ let squaresOfOdds xs = In the *unit-testing-with-fsharp* directory, run `dotnet test` again. The `dotnet test` command runs a build for the `MathService` project and then for the `MathService.Tests` project. After building both projects, it runs your tests. Two tests pass now. -## Completing the requirements +## Complete the requirements Now that you've made one test pass, it's time to write more. The next simple case works with a sequence whose only odd number is `1`. The number 1 is easier because the square of 1 is 1. Here's that next test: @@ -200,7 +200,7 @@ let squaresOfOdds xs = |> Seq.map square ``` -You've built a small library and a set of unit tests for that library. You've structured the solution so that adding new packages and tests is part of the normal workflow. You've concentrated most of your time and effort on solving the goals of the application. +You've built a small library and a set of unit tests for that library. You structured the solution so that adding new packages and tests is part of the normal workflow. You concentrated most of your time and effort on solving the goals of the application. ## See also diff --git a/docs/core/testing/unit-testing-mstest-configure.md b/docs/core/testing/unit-testing-mstest-configure.md new file mode 100644 index 0000000000000..55eab3e017def --- /dev/null +++ b/docs/core/testing/unit-testing-mstest-configure.md @@ -0,0 +1,99 @@ +--- +title: Configure MSTest +description: Learn how to configure MSTest. +author: Evangelink +ms.author: amauryleve +ms.date: 04/16/2024 +--- + +# Configure MSTest + +MSTest, Microsoft Testing Framework, is a test framework for .NET applications. It allows you to write and execute tests, and provide test suites with integration to Visual Studio and Visual Studio Code Test Explorers, the .NET CLI, and many CI pipelines. + +MSTest is a fully supported, open-source and a cross-platform test framework that works with all supported .NET targets (.NET Framework, .NET Core, .NET, UWP, WinUI, and so on) hosted on [GitHub](https://github.com/microsoft/testfx). + +## Runsettings + +A *.runsettings* file can be used to configure how unit tests are being run. To learn more about the runsettings and the configurations related to the platform, you can check out [VSTest runsettings documentation](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file) or [MSTest runner runsettings documentation](unit-testing-platform-extensions-vstest-bridge.md#runsettings-support). + +### MSTest element + +The following runsettings entries let you configure how MSTest behaves. + +| Configuration | Default | Values | +|---------------|---------|--------| +|**AssemblyCleanupTimeout**|0|Specify globally the timeout to apply on each instance of assembly cleanup method. `[Timeout]` attribute specified on the assembly cleanup method overrides the global timeout .| +|**AssemblyInitializeTimeout**|0|Specify globally the timeout to apply on each instance of assembly initialize method. `[Timeout]` attribute specified on the assembly initialize method overrides the global timeout .| +|**AssemblyResolution**|false|You can specify paths to extra assemblies when finding and running unit tests. For example, use these paths for dependency assemblies that aren't in the same directory as the test assembly. To specify a path, use a **Directory Path** element. Paths can include environment variables.

` `

This feature is only applied when using a .NET Framework target.| +|**CaptureTraceOutput**|true|Capture text messages coming from the `Console.Write*`, `Trace.Write*`, and `Debug.Write*` APIs that will be associated to the current running test.| +|**ClassCleanupLifecycle**|EndOfClass|If you want the class cleanup to occur at the end of assembly, set it to **EndOfAssembly**. (No longer supported starting from MSTest v4 as EndOfClass is the default and only [ClassCleanup]() behavior)| +|**ClassCleanupTimeout**|0|Specify globally the timeout to apply on each instance of class cleanup method. `[Timeout]` attribute specified on the class cleanup method overrides the global timeout.| +|**ClassInitializeTimeout**|0|Specify globally the timeout to apply on each instance of class initialize method. `[Timeout]` attribute specified on the class initialize method overrides the global timeout.| +|**DeleteDeploymentDirectoryAfterTestRunIsComplete**|true|To retain the deployment directory after a test run, set this value to **false**.| +|**DeploymentEnabled**|true|If you set the value to **false**, deployment items that you specify in your test method aren't copied to the deployment directory.| +|**DeployTestSourceDependencies**|true|A value indicating whether the test source references are to be deployed.| +|**EnableBaseClassTestMethodsFromOtherAssemblies**|true|A value indicating whether to enable discovery of test methods from base classes in a different assembly from the inheriting test class.| +|**ForcedLegacyMode**|false|In older versions of Visual Studio, the MSTest adapter was optimized to make it faster and more scalable. Some behavior, such as the order in which tests are run, might not be exactly as it was in previous editions of Visual Studio. Set the value to **true** to use the older test adapter.

For example, you might use this setting if you have an *app.config* file specified for a unit test.

We recommend that you consider refactoring your tests to allow you to use the newer adapter.| +|**MapInconclusiveToFailed**|false|If a test completes with an inconclusive status, it's mapped to the skipped status in **Test Explorer**. If you want inconclusive tests to be shown as failed, set the value to **true**.| +|**MapNotRunnableToFailed**|true|A value indicating whether a not runnable result is mapped to failed test.| +|**Parallelize**||Used to set the parallelization settings:

**Workers**: The number of threads/workers to be used for parallelization, which is by default **the number of processors on the current machine**.

**SCOPE**: The scope of parallelization. You can set it to **MethodLevel**. By default, it's **ClassLevel**.

`32MethodLevel`| +|**SettingsFile**||You can specify a test settings file to use with the MSTest adapter here. You can also specify a test settings file [from the settings menu](/visualstudio/test/configure-unit-tests-by-using-a-dot-runsettings-file#specify-a-run-settings-file-in-the-ide).

If you specify this value, you must also set the **ForcedLegacyMode** to **true**.

`true`| +|**TestCleanupTimeout**|0|Specify globally the timeout to apply on each instance of test cleanup method. `[Timeout]` attribute specified on the test cleanup method overrides the global timeout.| +|**TestInitializeTimeout**|0|Specify globally the timeout to apply on each instance of test initialize method. `[Timeout]` attribute specified on the test initialize method overrides the global timeout.| +|**TestTimeout**|0|Gets specified global test case timeout.| +|**TreatClassAndAssemblyCleanupWarningsAsErrors**|false|To see your failures in class cleanups as errors, set this value to **true**.| +|**TreatDiscoveryWarningsAsErrors**|false|To report test discovery warnings as errors, set this value to **true**.| + +### `TestRunParameter` element + +```xml + + + +``` + +Test run parameters provide a way to define variables and values that are available to the tests at run time. Access the parameters using the MSTest property: + +```csharp +private string _appUrl; +public TestContext TestContext { get; set; } + +[TestMethod] +public void HomePageTest() +{ + string _appUrl = TestContext.Properties["webAppUrl"]; +} +``` + +To use test run parameters, add a public property to your test class. + +### Example *.runsettings* file + +The following XML shows the contents of a typical *.runsettings* file. Copy this code and edit it to suit your needs. + +Each element of the file is optional because it has a default value. + +```xml + + + + + + + + + + + + + True + false + False + False + + + + + + +``` diff --git a/docs/core/tools/dotnet-install-script.md b/docs/core/tools/dotnet-install-script.md index d67aa14f88909..d5ed422b45a05 100644 --- a/docs/core/tools/dotnet-install-script.md +++ b/docs/core/tools/dotnet-install-script.md @@ -107,8 +107,8 @@ The install scripts do not update the registry on Windows. They just download th - `STS`: The most recent Standard Term Support release. - `LTS`: The most recent Long Term Support release. - - Two-part version in A.B format, representing a specific release (for example, `3.1` or `6.0`). - - Three-part version in A.B.Cxx format, representing a specific SDK release (for example, 6.0.1xx or 6.0.2xx). Available since the 5.0 release. + - Two-part version in A.B format, representing a specific release (for example, `3.1` or `8.0`). + - Three-part version in A.B.Cxx format, representing a specific SDK release (for example, 8.0.1xx or 8.0.2xx). Available since the 5.0 release. The `version` parameter overrides the `channel` parameter when any version other than `latest` is used. @@ -165,7 +165,7 @@ The install scripts do not update the registry on Windows. They just download th * `validated`: Builds that have had some internal testing done on them but are not yet released as preview or GA. This quality level is not intended for public use. * `preview`: The monthly public releases of the next version of .NET, intended for public use. Not recommended for production use. Intended to allow users to experiment and test the new major version before release. * `GA`: The final stable releases of the .NET SDK and Runtime. Intended for public use as well as production support. - + The `--quality` option works only in combination with `--channel`, but is not applicable for the `STS` and `LTS` channels and will be ignored if one of those channels is used. For an SDK installation, use a `channel` value that is in `A.B` or `A.B.Cxx` format. diff --git a/docs/core/tools/dotnet-new-sdk-templates.md b/docs/core/tools/dotnet-new-sdk-templates.md index 3822e906e6f55..c731660c6960e 100644 --- a/docs/core/tools/dotnet-new-sdk-templates.md +++ b/docs/core/tools/dotnet-new-sdk-templates.md @@ -60,7 +60,7 @@ The templates that ship with the .NET SDK have the following additional options: - **`-f|--framework `** - Specifies the [framework](../../standard/frameworks.md) to target. Values: `net8.0`, `net7.0`, `net6.0`, or `netcoreapp3.1` to create a .NET Class Library or `netstandard2.1` or `netstandard2.0` to create a .NET Standard Class Library. The default value for .NET SDK 8.0.x is `net8.0`. + Specifies the [framework](../../standard/frameworks.md) to target. Values: `net8.0`, `net7.0`, or `net6.0` to create a .NET Class Library, or `netstandard2.1` or `netstandard2.0` to create a .NET Standard Class Library. The default value for .NET SDK 8.0.x is `net8.0`. To create a project that targets a framework earlier than the SDK that you're using, see [`--framework` for `console` projects](#template-options) earlier in this article. diff --git a/docs/core/tools/dotnet-new.md b/docs/core/tools/dotnet-new.md index e3f68b5ddc01d..17bb3180210a4 100644 --- a/docs/core/tools/dotnet-new.md +++ b/docs/core/tools/dotnet-new.md @@ -145,10 +145,10 @@ Each template may have additional options defined. For more information, see [.N dotnet new xunit ``` -- Create a *global.json* in the current directory setting the SDK version to 3.1.101: +- Create a *global.json* in the current directory setting the SDK version to 8.0.101: ```dotnetcli - dotnet new globaljson --sdk-version 3.1.101 + dotnet new globaljson --sdk-version 8.0.101 ``` - Show help for the C# console application template: diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index ae80af9553e4e..21b871ded26c8 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -250,7 +250,7 @@ For more information, see the following resources: - Publish the project in the current directory, for a specific runtime and target framework: ```dotnetcli - dotnet publish --framework netcoreapp3.1 --runtime osx-x64 + dotnet publish --framework net8.0 --runtime osx-x64 ``` - Publish the specified project file: diff --git a/docs/core/tools/global-tools-how-to-create.md b/docs/core/tools/global-tools-how-to-create.md index 3fd0d48d9666d..e1f69e8e8e623 100644 --- a/docs/core/tools/global-tools-how-to-create.md +++ b/docs/core/tools/global-tools-how-to-create.md @@ -42,7 +42,7 @@ This is the first in a series of three tutorials. In this tutorial, you create a > > > Exe - > netcoreapp3.1;net5.0;net6.0 + > net8.0;net6.0 > > > ``` diff --git a/docs/core/tools/sdk-errors/netsdk1013.md b/docs/core/tools/sdk-errors/netsdk1013.md index 2d4142867211a..34f522a0d5b2b 100644 --- a/docs/core/tools/sdk-errors/netsdk1013.md +++ b/docs/core/tools/sdk-errors/netsdk1013.md @@ -11,14 +11,14 @@ f1_keywords: **This article applies to:** ✔️ .NET Core 3.1.100 SDK and later versions -The SDK tries to parse the values provided in the project file for `` or `` into a well known value. If the value is not recognized, the `TargetFrameworkIdentifier` or `TargetFrameworkVersion` value may be set to an empty string or `Unsupported`. +The SDK tries to parse the values provided in the project file for `` or `` into a well known value. If the value is not recognized, the `TargetFrameworkIdentifier` or `TargetFrameworkVersion` value might be set to an empty string or `Unsupported`. To resolve this, check the spelling of your `TargetFramework` value from the list of [supported frameworks](../../../standard/frameworks.md). You can also set the `TargetFrameworkIdentifier` and `TargetFrameworkVersion` properties directly in your project file. ```xml - .NETCOREAPP - 3.1 + .NETCoreApp + 8.0 ``` diff --git a/docs/core/tools/sdk-errors/netsdk1071.md b/docs/core/tools/sdk-errors/netsdk1071.md index d6cdc25d80d07..e01bed73f07a3 100644 --- a/docs/core/tools/sdk-errors/netsdk1071.md +++ b/docs/core/tools/sdk-errors/netsdk1071.md @@ -15,15 +15,15 @@ When the .NET SDK issues warning NETSDK1071, it suggests there may be a version ```xml - netcoreapp3.1 + net6.0 ``` -Since the TargetFramework automatically brings in a version of the metapackage, the versions will conflict should they ever differ. +Since the `TargetFramework` automatically brings in a version of the metapackage, the versions will conflict should they ever differ. To resolve this: -1. Consider, when targeting .NET Core or .NET Standard, avoiding explicit references to `Microsoft.NETCore.App` or `NETStandard.Library` in your project file. +1. When you target .NET Core or .NET Standard, consider avoiding explicit references to `Microsoft.NETCore.App` or `NETStandard.Library` in your project file. 2. If you need a specific version of the runtime when targeting .NET Core, use the ``property instead of referencing the metapackage directly. As an example, this could happen if you're using [self-contained deployments](../../deploying/index.md#publish-self-contained) and need a specific patch of the 1.0.0 LTS runtime. 3. If you need a specific version of `NetStandard.Library` when targeting .NET Standard, you can use the `` property and set it to the version you need. 4. Don't explicitly add or update references to either `Microsoft.NETCore.App` or `NETSTandard.Library` in .NET Framework projects. NuGet automatically installs any version of `NETStandard.Library` you need when using a .NET Standard-based NuGet package. diff --git a/docs/core/tools/sdk-errors/netsdk1082.md b/docs/core/tools/sdk-errors/netsdk1082.md index b9b5b3148d234..625930452e1c7 100644 --- a/docs/core/tools/sdk-errors/netsdk1082.md +++ b/docs/core/tools/sdk-errors/netsdk1082.md @@ -18,8 +18,8 @@ NETSDK1082 warns you that the runtime pack for your [runtime identifier](../../r EXISTINGVERSION - + ``` -In this example, TARGETFRAMEWORK represents values like `net6.0`, `net5.0`, or `netcoreapp3.1` -- basically anything that’s in the **.NET 5+ (and .NET Core)** list in [Supported target frameworks](../../../standard/frameworks.md#supported-target-frameworks). EXISTINGVERSION would need to be a valid version that has been released. For example, `6.0.7` for `net6.0`, `5.0.17` for `net5.0`, and so forth. For information about released versions, see [Download .NET 6.0](https://dotnet.microsoft.com/download/dotnet/6.0) and [Download .NET 5.0](https://dotnet.microsoft.com/download/dotnet/5.0). +In this example, `TARGETFRAMEWORK` represents values like `net8.0` or `net6.0` -- basically anything that’s in the **.NET 5+ (and .NET Core)** list in [Supported target frameworks](../../../standard/frameworks.md#supported-target-frameworks). `EXISTINGVERSION` needs to be a valid version that's been released. For example, `6.0.7` for `net6.0`. diff --git a/docs/core/versions/selection.md b/docs/core/versions/selection.md index 01aa8ab5cb504..3bf75203bde38 100644 --- a/docs/core/versions/selection.md +++ b/docs/core/versions/selection.md @@ -53,21 +53,21 @@ The process for selecting an SDK version is: For more information about SDK version selection, see the [Matching rules](../tools/global-json.md#matching-rules) and [rollForward](../tools/global-json.md#rollforward) sections of the [global.json overview](../tools/global-json.md) article. -## Target Framework Monikers define build time APIs +## Target framework monikers define build time APIs -You build your project against APIs defined in a **Target Framework Moniker** (TFM). You specify the [target framework](../../standard/frameworks.md) in the project file. Set the `TargetFramework` element in your project file as shown in the following example: +You build your project against APIs defined in a **target framework moniker** (TFM). You specify the [target framework](../../standard/frameworks.md) in the project file. Set the `TargetFramework` element in your project file as shown in the following example: ``` xml -net5.0 +net8.0 ``` -You may build your project against multiple TFMs. Setting multiple target frameworks is more common for libraries but can be done with applications as well. You specify a `TargetFrameworks` property (plural of `TargetFramework`). The target frameworks are semicolon-delimited as shown in the following example: +You can build your project against multiple TFMs. Setting multiple target frameworks is more common for libraries but can be done with applications as well. You specify a `TargetFrameworks` property (plural of `TargetFramework`). The target frameworks are semicolon-delimited as shown in the following example: ``` xml -net5.0;netcoreapp3.1;net47 +net8.0;net47 ``` -A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET 5 SDK includes the .NET 5 runtime, which is an implementation of the `net5.0` target framework. The .NET 5 SDK supports `netcoreapp2.0`, `netcoreapp2.1`, `netcoreapp3.0`, and so on, but not `net6.0` (or higher). You install the .NET 6 SDK to build for `net6.0`. +A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. For example, the .NET 8 SDK includes the .NET 8 runtime, which is an implementation of the `net8.0` target framework. The .NET 8 SDK supports `net7.0`, `net6.0`, and `net5.0`, but not `net9.0` (or higher). You install the .NET 9 SDK to build for `net9.0`. ### .NET Standard diff --git a/docs/core/whats-new/dotnet-5.md b/docs/core/whats-new/dotnet-5.md index 742707e8b7ea4..416202fac3f94 100644 --- a/docs/core/whats-new/dotnet-5.md +++ b/docs/core/whats-new/dotnet-5.md @@ -10,10 +10,10 @@ author: IEvangelist # What's new in .NET 5 -.NET 5 is the next major release of .NET Core following 3.1. We named this new release .NET 5 instead of .NET Core 4 for two reasons: +.NET 5 is the next major release of .NET Core following 3.1. This release was named .NET 5 instead of .NET Core 4 for two reasons: -- We skipped version numbers 4.x to avoid confusion with .NET Framework 4.x. -- We dropped "Core" from the name to emphasize that this is the main implementation of .NET going forward. .NET 5 supports more types of apps and more platforms than .NET Core or .NET Framework. +- Version numbers 4.x were skipped to avoid confusion with .NET Framework 4.x. +- "Core" was dropped from the name to emphasize that this is the main implementation of .NET going forward. .NET 5 supports more types of apps and more platforms than .NET Core or .NET Framework. ASP.NET Core 5.0 is based on .NET 5 but retains the name "Core" to avoid confusing it with ASP.NET MVC 5. Likewise, Entity Framework Core 5.0 retains the name "Core" to avoid confusing it with Entity Framework 5 and 6. diff --git a/docs/core/whats-new/dotnet-8/containers.md b/docs/core/whats-new/dotnet-8/containers.md index 435f2ab7c206c..a7066d41bb2af 100644 --- a/docs/core/whats-new/dotnet-8/containers.md +++ b/docs/core/whats-new/dotnet-8/containers.md @@ -68,7 +68,7 @@ For more information, see the [Improving multi-platform container support](https ### ASP.NET composite images -As part of an effort to improve containerization performance, new ASP.NET Docker images are available that have a composite version of the runtime. This composite is built by compiling multiple MSIL assemblies into a single ready-to-run (R2R) output binary. Because these assemblies are embedded into a single image, jitting takes less time, and the startup performance of apps improves. The other big advantage of the composite over the regular ASP.NET image is that the composite images have a smaller size on disk. +As part of an effort to improve containerization performance, new ASP.NET Docker images are available that have a composite version of the runtime. This composite is built by compiling multiple CIL assemblies into a single ready-to-run (R2R) output binary. Because these assemblies are embedded into a single image, jitting takes less time, and the startup performance of apps improves. The other big advantage of the composite over the regular ASP.NET image is that the composite images have a smaller size on disk. There is a caveat to be aware of. Since composites have multiple assemblies embedded into one, they have tighter version coupling. Apps can't use custom versions of framework or ASP.NET binaries. diff --git a/docs/csharp/advanced-topics/expression-trees/index.md b/docs/csharp/advanced-topics/expression-trees/index.md index 798076ca42faf..a5815b961482a 100644 --- a/docs/csharp/advanced-topics/expression-trees/index.md +++ b/docs/csharp/advanced-topics/expression-trees/index.md @@ -16,9 +16,9 @@ You've likely already written code that uses Expression trees. Entity Framework' When you want to have a richer interaction, you need to use *Expression Trees*. Expression Trees represent code as a structure that you examine, modify, or execute. These tools give you the power to manipulate code during run time. You write code that examines running algorithms, or injects new capabilities. In more advanced scenarios, you modify running algorithms and even translate C# expressions into another form for execution in another environment. -You compile and run code represented by expression trees. Building and running expression trees enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to use expression trees to build dynamic queries](../../programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md). +You compile and run code represented by expression trees. Building and running expression trees enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to use expression trees to build dynamic queries](../../linq/how-to-build-dynamic-queries.md). -Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and .NET and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (MSIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). +Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and .NET and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (CIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. diff --git a/docs/csharp/advanced-topics/interop/walkthrough-office-programming.md b/docs/csharp/advanced-topics/interop/walkthrough-office-programming.md index bdfcebbd5b812..0fbee4203316c 100644 --- a/docs/csharp/advanced-topics/interop/walkthrough-office-programming.md +++ b/docs/csharp/advanced-topics/interop/walkthrough-office-programming.md @@ -104,7 +104,7 @@ In Visual Studio, select **Clean Solution** on the **Build** menu. Otherwise, th 1. Run the application again, but don't select **Clean Solution**. 1. Select the **Start**. Locate **Microsoft Visual Studio \** and open a developer command prompt. -1. Type `ildasm` in the Developer Command Prompt for Visual Studio window, and then press ENTER. The IL DASM window appears. +1. Type `ildasm` in the Developer Command Prompt for Visual Studio window, and then press Enter. The IL DASM window appears. 1. On the **File** menu in the IL DASM window, select **File** > **Open**. Double-click **Visual Studio \**, and then double-click **Projects**. Open the folder for your project, and look in the bin/Debug folder for *your project name*.dll. Double-click *your project name*.dll. A new window displays your project's attributes, in addition to references to other modules and assemblies. The assembly includes the namespaces `Microsoft.Office.Interop.Excel` and `Microsoft.Office.Interop.Word`. By default in Visual Studio, the compiler imports the types you need from a referenced PIA into your assembly. For more information, see [How to: View Assembly Contents](../../../standard/assembly/view-contents.md). 1. Double-click the **MANIFEST** icon. A window appears that contains a list of assemblies that contain items referenced by the project. `Microsoft.Office.Interop.Excel` and `Microsoft.Office.Interop.Word` aren't in the list. Because you imported the types your project needs into your assembly, you aren't required to install references to a PIA. Importing the types into your assembly makes deployment easier. The PIAs don't have to be present on the user's computer. An application doesn't require deployment of a specific version of a PIA. Applications can work with multiple versions of Office, provided that the necessary APIs exist in all versions. Because deployment of PIAs is no longer necessary, you can create an application in advanced scenarios that works with multiple versions of Office, including earlier versions. Your code can't use any APIs that aren't available in the version of Office you're working with. It isn't always clear whether a particular API was available in an earlier version. Working with earlier versions of Office isn't recommended. 1. Close the manifest window and the assembly window. diff --git a/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/finished/IssuePRreport.csproj b/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/finished/IssuePRreport.csproj index 0883ce5f25d05..c470029f00cc8 100644 --- a/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/finished/IssuePRreport.csproj +++ b/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/finished/IssuePRreport.csproj @@ -9,7 +9,7 @@ - + diff --git a/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/start/IssuePRreport.csproj b/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/start/IssuePRreport.csproj index 0883ce5f25d05..c470029f00cc8 100644 --- a/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/start/IssuePRreport.csproj +++ b/docs/csharp/asynchronous-programming/snippets/generate-consume-asynchronous-streams/start/IssuePRreport.csproj @@ -9,7 +9,7 @@ - + diff --git a/docs/csharp/how-to/index.md b/docs/csharp/how-to/index.md index e58b354d30b1b..b82ea1958b685 100644 --- a/docs/csharp/how-to/index.md +++ b/docs/csharp/how-to/index.md @@ -102,19 +102,17 @@ LINQ enables you to write code to query any data source that supports the LINQ query expression pattern. These articles help you understand the pattern and work with different data sources. -- [Query a collection](../programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md). +- [Query a collection](../linq/how-to-query-collections.md). - [Use `var` in query expressions](../programming-guide/classes-and-structs/how-to-use-implicitly-typed-local-variables-and-arrays-in-a-query-expression.md). - [Return subsets of element properties from a query](../programming-guide/classes-and-structs/how-to-return-subsets-of-element-properties-in-a-query.md). - [Write queries with complex filtering](../../standard/linq/write-queries-complex-filtering.md). - [Sort elements of a data source](../../standard/linq/sort-elements.md). - [Sort elements on multiple keys](../../standard/linq/sort-elements-multiple-keys.md). - [Control the type of a projection](../../standard/linq/control-type-projection.md). -- [Count occurrences of a value in a source sequence](../programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md). +- [Count occurrences of a value in a source sequence](../linq/how-to-query-strings.md). - [Calculate intermediate values](../../standard/linq/calculate-intermediate-values.md). -- [Merge data from multiple sources](../programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md). -- [Find the set difference between two sequences](../programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md). - [Debug empty query results](../../standard/linq/debug-empty-query-results-sets.md). -- [Add custom methods to LINQ queries](../programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md). +- [Add custom methods to LINQ queries](../linq/how-to-extend-linq.md). ## Multiple threads and async processing diff --git a/docs/csharp/language-reference/compiler-messages/cs8352.md b/docs/csharp/language-reference/compiler-messages/cs8352.md index 06f7bebaec31e..f2f711f3f3864 100644 --- a/docs/csharp/language-reference/compiler-messages/cs8352.md +++ b/docs/csharp/language-reference/compiler-messages/cs8352.md @@ -11,11 +11,11 @@ helpviewer_keywords: Cannot use variable 'variable' in this context because it may expose referenced variables outside of their declaration scope. -This error indicates potential undefined behavior when there's a risk of accessing a stack allocated variable after it has already been deleted from the stack. +This error indicates potential undefined behavior when there's a risk of accessing a stack-allocated variable after it's already been deleted from the stack. ## To correct this error -You fix `CS8352` by ensuring the variable's scope is at least as wide as the variable that refers to it. You do this by either allocating the storage on a heap, or in the stack on the calling context. +You fix `CS8352` by ensuring the variable's scope is at least as wide as the variable that refers to it. You do this by allocating the storage on a heap, or in the stack on the calling context. ## Example diff --git a/docs/csharp/language-reference/compiler-options/advanced.md b/docs/csharp/language-reference/compiler-options/advanced.md index 34b8f613e170b..23793eed76ed4 100644 --- a/docs/csharp/language-reference/compiler-options/advanced.md +++ b/docs/csharp/language-reference/compiler-options/advanced.md @@ -86,7 +86,7 @@ When you specify [**DebugType**](code-generation.md#debugtype), the compiler cre ## PathMap > [!NOTE] -Specifying **PathMap** will prevent breakpoints from working in local debug builds. Only set **PathMap** for production or [continuous integration builds](https://learn.microsoft.com/dotnet/core/project-sdk/msbuild-props#continuousintegrationbuild). +Specifying **PathMap** will prevent breakpoints from working in local debug builds. Only set **PathMap** for production or [continuous integration builds](../../../core/project-sdk/msbuild-props.md#continuousintegrationbuild). The **PathMap** compiler option specifies how to map physical paths to source path names output by the compiler. This option maps each physical path on the machine where the compiler runs to a corresponding path that should be written in the output files. In the following example, `path1` is the full path to the source files in the current environment, and `sourcePath1` is the source path substituted for `path1` in any output files. To specify multiple mapped source paths, separate each with a comma. diff --git a/docs/csharp/language-reference/compiler-options/security.md b/docs/csharp/language-reference/compiler-options/security.md index 4ba3fa72b183b..cec2cd22d057d 100644 --- a/docs/csharp/language-reference/compiler-options/security.md +++ b/docs/csharp/language-reference/compiler-options/security.md @@ -2,9 +2,9 @@ description: "C# Compiler Options for security. These options control signing assemblies or address space layout." title: "C# Compiler Options - security options" ms.date: 03/12/2021 -f1_keywords: +f1_keywords: - "cs.build.options" -helpviewer_keywords: +helpviewer_keywords: - "PublicSign compiler option [C#]" - "DelaySign compiler option [C#]" - "KeyFile compiler option [C#]" @@ -61,7 +61,7 @@ Specifies the name of the cryptographic key container. container ``` -`container` is the name of the strong name key container. When the **KeyContainer** option is used, the compiler creates a sharable component. The compiler inserts a public key from the specified container into the assembly manifest and signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. `sn -i` installs the key pair into a container. This option isn't supported when the compiler runs on CoreCLR. To sign an assembly when building on CoreCLR, use the [**KeyFile**](#keyfile) option. If you compile with [**TargetType**](output.md#targettype), the name of the key file is held in the module and incorporated into the assembly when you compile this module into an assembly with [**AddModules**](inputs.md#addmodules). You can also specify this option as a custom attribute () in the source code for any Microsoft intermediate language (MSIL) module. You can also pass your encryption information to the compiler with [**KeyFile**](#keyfile). Use [**DelaySign**](#delaysign) to add the public key to the assembly manifest but signing the assembly until it has been tested. For more information, see [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) and [Delay Signing an Assembly](../../../standard/assembly/delay-sign.md). +`container` is the name of the strong name key container. When the **KeyContainer** option is used, the compiler creates a sharable component. The compiler inserts a public key from the specified container into the assembly manifest and signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. `sn -i` installs the key pair into a container. This option isn't supported when the compiler runs on CoreCLR. To sign an assembly when building on CoreCLR, use the [**KeyFile**](#keyfile) option. If you compile with [**TargetType**](output.md#targettype), the name of the key file is held in the module and incorporated into the assembly when you compile this module into an assembly with [**AddModules**](inputs.md#addmodules). You can also specify this option as a custom attribute () in the source code for any common intermediate language (CIL) module. You can also pass your encryption information to the compiler with [**KeyFile**](#keyfile). Use [**DelaySign**](#delaysign) to add the public key to the assembly manifest but signing the assembly until it has been tested. For more information, see [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) and [Delay Signing an Assembly](../../../standard/assembly/delay-sign.md). ## HighEntropyVA diff --git a/docs/csharp/language-reference/configure-language-version.md b/docs/csharp/language-reference/configure-language-version.md index 3d9276e8d342b..7d3273af4da93 100644 --- a/docs/csharp/language-reference/configure-language-version.md +++ b/docs/csharp/language-reference/configure-language-version.md @@ -70,4 +70,4 @@ The following table shows all current C# language versions. Older compilers migh [!INCLUDE [langversion-table](includes/langversion-table.md)] >[!NOTE] ->Specifying **LangVersion** with the `default` value is different from omitting the **LangVersion** option. Specifying `default` uses the latest version of the language that the compiler supports, without taking into account the target framework. For example, building a project that targets .NET 6 from the current version of Visual Studio 2022 uses C# 10 if **LangVersion** isn't specified, but uses C# 11 if **LangVersion** is set to `default`. +>Specifying **LangVersion** with the `default` value is different from omitting the **LangVersion** option. Specifying `default` uses the latest version of the language that the compiler supports, without taking into account the target framework. For example, building a project that targets .NET 6 from the current version of Visual Studio 2022 uses C# 10 if **LangVersion** isn't specified, but uses C# 12 if **LangVersion** is set to `default`. diff --git a/docs/csharp/language-reference/keywords/from-clause.md b/docs/csharp/language-reference/keywords/from-clause.md index 5f5747316daf2..f0f83950f4f82 100644 --- a/docs/csharp/language-reference/keywords/from-clause.md +++ b/docs/csharp/language-reference/keywords/from-clause.md @@ -26,7 +26,7 @@ In the following example, `numbers` is the data source and `num` is the range va ## The range variable -The compiler infers the type of the range variable when the data source implements . For example, if the source has a type of `IEnumerable`, then the range variable is inferred to be `Customer`. The only time that you must specify the type explicitly is when the source is a non-generic `IEnumerable` type such as . For more information, see [How to query an ArrayList with LINQ](../../programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md). +The compiler infers the type of the range variable when the data source implements . For example, if the source has a type of `IEnumerable`, then the range variable is inferred to be `Customer`. The only time that you must specify the type explicitly is when the source is a non-generic `IEnumerable` type such as . For more information, see [How to query an ArrayList with LINQ](../../linq/how-to-query-collections.md). In the previous example `num` is inferred to be of type `int`. Because the range variable is strongly typed, you can call methods on it or use it in other operations. For example, instead of writing `select num`, you could write `select num.ToString()` to cause the query expression to return a sequence of strings instead of integers. Or you could write `select num + 10` to cause the expression to return the sequence 14, 11, 13, 12, 10. For more information, see [select clause](select-clause.md). diff --git a/docs/csharp/language-reference/keywords/group-clause.md b/docs/csharp/language-reference/keywords/group-clause.md index e0993f30f585a..fb750f14afd99 100644 --- a/docs/csharp/language-reference/keywords/group-clause.md +++ b/docs/csharp/language-reference/keywords/group-clause.md @@ -48,7 +48,7 @@ The following example shows the use of a bool value for a key to divide the resu ### Grouping by numeric range -The next example uses an expression to create numeric group keys that represent a percentile range. Note the use of [let](let-clause.md) as a convenient location to store a method call result, so that you don't have to call the method two times in the `group` clause. For more information about how to safely use methods in query expressions, see [Handle exceptions in query expressions](../../linq/handle-exceptions-in-query-expressions.md). +The next example uses an expression to create numeric group keys that represent a percentile range. Note the use of [let](let-clause.md) as a convenient location to store a method call result, so that you don't have to call the method two times in the `group` clause. For more information about how to safely use methods in query expressions, see [Handle exceptions in query expressions](../../linq/get-started/write-linq-queries.md). [!code-csharp[cscsrefQueryKeywords#15](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsCsrefQueryKeywords/CS/Group.cs#15)] @@ -60,7 +60,7 @@ Use a composite key when you want to group elements according to more than one k group person by new {name = person.surname, city = person.city}; ``` -Use a named type if you must pass the query variable to another method. Create a special class using auto-implemented properties for the keys, and then override the and methods. You can also use a struct, in which case you do not strictly have to override those methods. For more information see [How to implement a lightweight class with auto-implemented properties](../../programming-guide/classes-and-structs/how-to-implement-a-lightweight-class-with-auto-implemented-properties.md) and [How to query for duplicate files in a directory tree](../../programming-guide/concepts/linq/how-to-query-for-duplicate-files-in-a-directory-tree-linq.md). The latter article has a code example that demonstrates how to use a composite key with a named type. +Use a named type if you must pass the query variable to another method. Create a special class using auto-implemented properties for the keys, and then override the and methods. You can also use a struct, in which case you do not strictly have to override those methods. For more information see [How to implement a lightweight class with auto-implemented properties](../../programming-guide/classes-and-structs/how-to-implement-a-lightweight-class-with-auto-implemented-properties.md) and [How to query for duplicate files in a directory tree](../../linq/how-to-query-files-and-directories.md). The latter article has a code example that demonstrates how to use a composite key with a named type. ## Example 1 diff --git a/docs/csharp/language-reference/keywords/let-clause.md b/docs/csharp/language-reference/keywords/let-clause.md index a123fb8f3d0e5..d5782d983f782 100644 --- a/docs/csharp/language-reference/keywords/let-clause.md +++ b/docs/csharp/language-reference/keywords/let-clause.md @@ -29,4 +29,4 @@ In the following example `let` is used in two ways: - [Query Keywords (LINQ)](query-keywords.md) - [LINQ in C#](../../linq/index.md) - [Language Integrated Query (LINQ)](/dotnet/csharp/linq/) -- [Handle exceptions in query expressions](../../linq/handle-exceptions-in-query-expressions.md) +- [Handle exceptions in query expressions](../../linq/get-started/write-linq-queries.md) diff --git a/docs/csharp/language-reference/keywords/reference-types.md b/docs/csharp/language-reference/keywords/reference-types.md index 9d9163ed49e18..33f895f4c32e0 100644 --- a/docs/csharp/language-reference/keywords/reference-types.md +++ b/docs/csharp/language-reference/keywords/reference-types.md @@ -23,9 +23,9 @@ There are two kinds of types in C#: reference types and value types. Variables o C# also provides the following built-in reference types: -- [dynamic](../builtin-types/reference-types.md) -- [object](../builtin-types/reference-types.md) -- [string](../builtin-types/reference-types.md) +- [dynamic](../builtin-types/reference-types.md#the-dynamic-type) +- [object](../builtin-types/reference-types.md#the-object-type) +- [string](../builtin-types/reference-types.md#the-string-type) ## See also diff --git a/docs/csharp/language-reference/keywords/snippets/Namespaces3.cs b/docs/csharp/language-reference/keywords/snippets/Namespaces3.cs deleted file mode 100644 index 466f2ee6f7679..0000000000000 --- a/docs/csharp/language-reference/keywords/snippets/Namespaces3.cs +++ /dev/null @@ -1,15 +0,0 @@ -// -using System; - -public class TestCopy{ - - public void CopyDirectory() - { - // - // Duplicate a directory - Microsoft.VisualBasic.FileIO.FileSystem.CopyDirectory( - @"C:\original_directory", - @"C:\copy_of_original_directory"); - // - } -} diff --git a/docs/csharp/language-reference/keywords/using-directive.md b/docs/csharp/language-reference/keywords/using-directive.md index 9c1e0643a90e2..9282ba32a2d57 100644 --- a/docs/csharp/language-reference/keywords/using-directive.md +++ b/docs/csharp/language-reference/keywords/using-directive.md @@ -160,16 +160,6 @@ The following example shows how to define a `using` directive and a `using` alia Beginning with C# 12, you can create aliases for types that were previously restricted, including [tuple types](../builtin-types/value-tuples.md#tuple-field-names), pointer types, and other unsafe types. For more information on the updated rules, see the [feature spec](~/_csharplang/proposals/csharp-12.0/using-alias-types.md). -## How to use the Visual Basic `My` namespace - -The namespace (`My` in Visual Basic) provides easy and intuitive access to a number of .NET classes, enabling you to write code that interacts with the computer, application, settings, resources, and so on. Although originally designed for use with Visual Basic, the `MyServices` namespace can be used in C# applications. - -For more information about using the `MyServices` namespace from Visual Basic, see [Development with My](../../../visual-basic/developing-apps/development-with-my/index.md). - -You need to add a reference to the *Microsoft.VisualBasic.dll* assembly in your project. Not all the classes in the `MyServices` namespace can be called from a C# application: for example, the class is not compatible. In this particular case, the static methods that are part of , which are also contained in VisualBasic.dll, can be used instead. For example, here is how to use one such method to duplicate a directory: - -:::code language="csharp" source="./snippets/Namespaces3.cs" id="Snippet20"::: - ## C# language specification For more information, see [Using directives](~/_csharpstandard/standard/namespaces.md#145-using-directives) in the [C# Language Specification](~/_csharpstandard/standard/README.md). The language specification is the definitive source for C# syntax and usage. diff --git a/docs/csharp/language-reference/operators/snippets/shared/ConditionalOperator.cs b/docs/csharp/language-reference/operators/snippets/shared/ConditionalOperator.cs index e6931e6fce710..bae892ccc0278 100644 --- a/docs/csharp/language-reference/operators/snippets/shared/ConditionalOperator.cs +++ b/docs/csharp/language-reference/operators/snippets/shared/ConditionalOperator.cs @@ -24,8 +24,8 @@ private static void BasicExample() private static void ConditionalRefExpressions() { // - int[] smallArray = [1, 2, 3, 4, 5]; - int[] largeArray = [10, 20, 30, 40, 50]; + int[] smallArray = {1, 2, 3, 4, 5}; + int[] largeArray = {10, 20, 30, 40, 50}; int index = 7; ref int refValue = ref ((index < 5) ? ref smallArray[index] : ref largeArray[index - 5]); diff --git a/docs/csharp/language-reference/statements/declarations.md b/docs/csharp/language-reference/statements/declarations.md index 953821b2df101..18b5a69055cd3 100644 --- a/docs/csharp/language-reference/statements/declarations.md +++ b/docs/csharp/language-reference/statements/declarations.md @@ -67,7 +67,7 @@ In pattern matching, the `var` keyword is used in a [`var` pattern](../operators When you declare a local variable and add the `ref` keyword before the variable's type, you declare a *reference variable*, or a `ref` local: ```csharp -ref int alias = ref variable; +ref int aliasOfvariable = ref variable; ``` A reference variable is a variable that refers to another variable, which is called the *referent*. That is, a reference variable is an *alias* to its referent. When you assign a value to a reference variable, that value is assigned to the referent. When you read the value of a reference variable, the referent's value is returned. The following example demonstrates that behavior: diff --git a/docs/csharp/language-reference/statements/snippets/declarations/ReferenceVariables.cs b/docs/csharp/language-reference/statements/snippets/declarations/ReferenceVariables.cs index 495a69bbb2662..0fef57730edf5 100644 --- a/docs/csharp/language-reference/statements/snippets/declarations/ReferenceVariables.cs +++ b/docs/csharp/language-reference/statements/snippets/declarations/ReferenceVariables.cs @@ -11,14 +11,14 @@ private static void AliasToLocalVariable() { // int a = 1; - ref int alias = ref a; - Console.WriteLine($"(a, alias) is ({a}, {alias})"); // output: (a, alias) is (1, 1) + ref int aliasOfa = ref a; + Console.WriteLine($"(a, aliasOfa) is ({a}, {aliasOfa})"); // output: (a, aliasOfa) is (1, 1) a = 2; - Console.WriteLine($"(a, alias) is ({a}, {alias})"); // output: (a, alias) is (2, 2) + Console.WriteLine($"(a, aliasOfa) is ({a}, {aliasOfa})"); // output: (a, aliasOfa) is (2, 2) - alias = 3; - Console.WriteLine($"(a, alias) is ({a}, {alias})"); // output: (a, alias) is (3, 3) + aliasOfa = 3; + Console.WriteLine($"(a, aliasOfa) is ({a}, {aliasOfa})"); // output: (a, aliasOfa) is (3, 3) // } diff --git a/docs/csharp/language-reference/toc.yml b/docs/csharp/language-reference/toc.yml index 2718f5bb1b842..b0cd4097bf617 100644 --- a/docs/csharp/language-reference/toc.yml +++ b/docs/csharp/language-reference/toc.yml @@ -443,20 +443,20 @@ items: CS7071, CS7079, CS8090, CS8203 - name: Constructor declarations href: ./compiler-messages/constructor-errors.md - displayName: > + displayName: > Primary constructors, CS0514, CS0515, CS0516, CS0517, CS0522, CS0526, CS0568, CS0710, CS0768, CS0824, CS8054, CS8091, CS8358, CS8862, CS8867, CS8868, CS8878, CS8910, CS8958, CS8982, CS8983, CS9105, CS9106, CS9107, CS9108, CS9109, CS9110, CS9111, CS9112, CS9113, CS9114, CS9115, CS9116, CS9117, CS9118, CS9119, CS9120, CS9121, CS9122, CS9124, CS9136, CS9179 - name: Parameter / argument mismatch href: ./compiler-messages/parameter-argument-mismatch.md - displayName: > + displayName: > CS0182, CS0591, CS0599, CS0617, CS0633, CS0643, CS0655, CS0839, CS1016, CS1739, CS1740, CS1742, CS1744, CS1746, CS7036, CS7067, CS8196, CS8324, CS8861, CS8905, CS8943, CS8944, CS8945, CS8948, CS8949, CS8950, CS8951, CS8964, CS8965, CS8966 - name: Reference parameters href: ./compiler-messages/ref-modifiers-errors.md displayName: > - ref safety, + ref safety, CS0192, CS0199, CS0206, CS0631, CS0767, CS1510, CS1605, CS1623, CS1649, CS1651, CS1655, CS1657, CS1741, CS1939, CS1988, CS7084, CS8166, CS8167, CS8168, CS8169. CS8325, CS8326, CS8327, CS8329, CS8330, CS8331, CS8332, CS8337, CS8338, CS8345, CS8351, CS8373, CS8374, CS8388, CS8977, CS9072, CS9077, CS9078, CS9079, CS9085, CS9086, CS9087, CS9089, CS9091, CS9092, @@ -474,7 +474,7 @@ items: displayName: CS8509, CS9134, CS9135 - name: Array declarations href: ./compiler-messages/array-declaration-errors.md - displayName: > + displayName: > CS0022, CS0178, CS0248, CS0251, CS0270, CS0611, CS0623, CS0650, CS0719, CS0747, CS0820, CS0826, CS0846, CS1552, CS1586, CS1920, CS1921, CS1925, CS1954, CS3007, CS3016, CS9174, CS9176, CS9185, CS9186, CS9187, CS9188, CS9203, CS9208, CS9209, CS9210 @@ -483,7 +483,7 @@ items: displayName: CS9164, CS9165, CS9166, CS9167, CS9168, CS9169, CS9172, CS9173, CS9180, CS9181, CS9182, CS9183, CS9184 - name: Lambda expressions href: ./compiler-messages/lambda-expression-errors.md - displayName: > + displayName: > CS0748, CS1621, CS1628, CS1632, CS1673, CS1686, CS1706, CS1989, CS8030, CS8175, CS8916, CS8971, CS8972, CS8975, CS9098, CS9099, CS9100 - name: Restrictions on expression trees @@ -494,7 +494,7 @@ items: CS8514, CS8640, CS8642, CS8790, CS8791, CS8792, CS8810, CS8849, CS8927, CS8952, CS9170, CS9175 - name: Using directive and aliases href: ./compiler-messages/using-directive-errors.md - displayName: > + displayName: > CS0105, CS0138, CS0431, CS0432, CS0440, CS0576, CS0687, CS1529, CS1537, CS7000, CS7007, CS8019, CS8083, CS8085, CS8914, CS8915, CS8933, CS9055, CS9130, CS9131, CS9132, CS9133, CS9162, CS9163 - name: Source generators @@ -2010,6 +2010,8 @@ items: href: ./compiler-messages/cs8333.md - name: CS8334 href: ./compiler-messages/cs8334.md + - name: CS8352 + href: ./compiler-messages/cs8352.md - name: CS8354 href: ./compiler-messages/cs8354.md - name: CS8355 diff --git a/docs/csharp/linq/dynamically-specify-predicate-filters-at-runtime.md b/docs/csharp/linq/dynamically-specify-predicate-filters-at-runtime.md deleted file mode 100644 index 2cc69f356db9a..0000000000000 --- a/docs/csharp/linq/dynamically-specify-predicate-filters-at-runtime.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Dynamically specify predicate filters at run time (LINQ in C#) -description: Learn how to dynamically specify predicate filters at run time using LINQ in C#. -ms.date: 12/01/2016 -ms.assetid: 90238470-0767-497c-916c-52d0d16845e0 ---- -# Dynamically specify predicate filters at run time - -In some cases, you don't know until run time how many predicates you have to apply to source elements in the `where` clause. One way to dynamically specify multiple predicate filters is to use the method, as shown in the following example. The query will return different results based on the value of `id` when the query is executed. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/RuntimeFiltering.cs" id="runtime_filtering_1"::: - -## Using different queries at runtime - -You can use control flow statements, such as `if... else` or `switch`, to select among predetermined alternative queries. In the following example, `studentQuery` uses a different `where` clause if the runtime value of `oddYear` is `true` or `false`. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/RuntimeFiltering.cs" id="runtime_filtering_2"::: - -## See also - -- [Language Integrated Query (LINQ)](index.md) -- [where clause](../language-reference/keywords/where-clause.md) -- [Querying based on runtime state](../advanced-topics/expression-trees/debugview-syntax.md) diff --git a/docs/csharp/linq/get-started/features-that-support-linq.md b/docs/csharp/linq/get-started/features-that-support-linq.md index a1af6c473aa7b..87a572e4af696 100644 --- a/docs/csharp/linq/get-started/features-that-support-linq.md +++ b/docs/csharp/linq/get-started/features-that-support-linq.md @@ -1,7 +1,7 @@ --- title: "C# Features That Support LINQ" description: Learn about C# features to use with LINQ queries and in other contexts. -ms.date: 12/14/2023 +ms.date: 04/22/2024 helpviewer_keywords: - "LINQ [C#], features supporting LINQ" --- @@ -78,3 +78,30 @@ An [extension method](../../programming-guide/classes-and-structs/extension-meth ## Lambda Expressions A [lambda expressions](../../language-reference/operators/lambda-expressions.md) is an inline function that uses the `=>` operator to separate input parameters from the function body and can be converted at compile time to a delegate or an expression tree. In LINQ programming, you encounter lambda expressions when you make direct method calls to the standard query operators. + +## Expressions as data + +Query objects are composable, meaning that you can return a query from a method. Objects that represent queries don't store the resulting collection, but rather the steps to produce the results when needed. The advantage of returning query objects from methods is that they can be further composed or modified. Therefore any return value or `out` parameter of a method that returns a query must also have that type. If a method materializes a query into a concrete or type, it returns the query results instead of the query itself. A query variable that is returned from a method can still be composed or modified. + +In the following example, the first method `QueryMethod1` returns a query as a return value, and the second method `QueryMethod2` returns a query as an `out` parameter (`returnQ` in the example). In both cases, it's a query that is returned, not query results. + +:::code language="csharp" source="./snippets/SnippetApp/ReturnQueryFromMethod.cs" id="return_query_from_method_1"::: + +Query `myQuery1` is executed in the following foreach loop. + +:::code language="csharp" source="./snippets/SnippetApp/ReturnQueryFromMethod.cs" id="return_query_from_method_2"::: + +Rest the mouse pointer over `myQuery1` to see its type. + +You also can execute the query returned from `QueryMethod1` directly, without using `myQuery1`. + +:::code language="csharp" source="./snippets/SnippetApp/ReturnQueryFromMethod.cs" id="return_query_from_method_3"::: + +Rest the mouse pointer over the call to `QueryMethod1` to see its return type. + +`QueryMethod2` returns a query as the value of its `out` parameter: +:::code language="csharp" source="./snippets/SnippetApp/ReturnQueryFromMethod.cs" id="return_query_from_method_4"::: + +You can modify a query by using query composition. In this case, the previous query object is used to create a new query object. This new object returns different results than the original query object. + +:::code language="csharp" source="./snippets/SnippetApp/ReturnQueryFromMethod.cs" id="return_query_from_method_5"::: diff --git a/docs/csharp/linq/get-started/introduction-to-linq-queries.md b/docs/csharp/linq/get-started/introduction-to-linq-queries.md index 53a165cf2f302..95877d94d3aac 100644 --- a/docs/csharp/linq/get-started/introduction-to-linq-queries.md +++ b/docs/csharp/linq/get-started/introduction-to-linq-queries.md @@ -1,14 +1,14 @@ --- title: "Introduction to LINQ Queries (C#)" description: LINQ offers a consistent model for queries on data across various kinds of data sources and formats. In a LINQ query, you're always working with objects. -ms.date: 12/14/2023 +ms.date: 04/22/2024 helpviewer_keywords: - "deferred execution [LINQ]" - "LINQ, queries" - "LINQ, deferred execution" - "queries [LINQ], about LINQ queries" --- -# Introduction to LINQ Queries (C#) +# Introduction to LINQ Queries in C\# A *query* is an expression that retrieves data from a data source. Different data sources have different native query languages, for example SQL for relational databases and XQuery for XML. Developers must learn a new query language for each type of data source or data format that they must support. LINQ simplifies this situation by offering a consistent C# language model for kinds of data sources and formats. In a LINQ query, you always work with C# objects. You use the same basic coding patterns to query and transform data in XML documents, SQL databases, .NET collections, and any other format when a LINQ provider is available. @@ -51,43 +51,140 @@ IQueryable custQuery = For more information about how to create specific types of data sources, see the documentation for the various LINQ providers. However, the basic rule is simple: a LINQ data source is any object that supports the generic interface, or an interface that inherits from it, typically . > [!NOTE] -> Types such as that support the non-generic interface can also be used as a LINQ data source. For more information, see [How to query an ArrayList with LINQ (C#)](../../programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md). +> Types such as that support the non-generic interface can also be used as a LINQ data source. For more information, see [How to query an ArrayList with LINQ (C#)](../how-to-query-collections.md). ## The Query The query specifies what information to retrieve from the data source or sources. Optionally, a query also specifies how that information should be sorted, grouped, and shaped before being returned. A query is stored in a query variable and initialized with a query expression. You use [C# query syntax](../../language-reference/keywords/query-keywords.md) to write queries. -The query in the previous example returns all the even numbers from the integer array. The query expression contains three clauses: `from`, `where` and `select`. (If you're familiar with SQL, you noticed that the ordering of the clauses is reversed from the order in SQL.) The `from` clause specifies the data source, the `where` clause applies the filter, and the `select` clause specifies the type of the returned elements. All the query clauses are discussed in detail in this section. For now, the important point is that in LINQ, the query variable itself takes no action and returns no data. It just stores the information that is required to produce the results when the query is executed at some later point. For more information about how queries are constructed, see [Standard Query Operators Overview (C#)](../standard-query-operators/index.md). +The query in the previous example returns all the even numbers from the integer array. The query expression contains three clauses: `from`, `where`, and `select`. (If you're familiar with SQL, you noticed that the ordering of the clauses is reversed from the order in SQL.) The `from` clause specifies the data source, the `where` clause applies the filter, and the `select` clause specifies the type of the returned elements. All the query clauses are discussed in detail in this section. For now, the important point is that in LINQ, the query variable itself takes no action and returns no data. It just stores the information that is required to produce the results when the query is executed at some later point. For more information about how queries are constructed, see [Standard Query Operators Overview (C#)](../standard-query-operators/index.md). > [!NOTE] > Queries can also be expressed by using method syntax. For more information, see [Query Syntax and Method Syntax in LINQ](write-linq-queries.md). -## Query Execution +## Classification of standard query operators by manner of execution -### Deferred Execution +The LINQ to Objects implementations of the standard query operator methods execute in one of two main ways: *immediate* or *deferred*. The query operators that use deferred execution can be additionally divided into two categories: *streaming* and *nonstreaming*. -The query variable itself only stores the query commands. The actual execution of the query is deferred until you iterate over the query variable in a `foreach` statement. This concept is referred to as *deferred execution* and is demonstrated in the following example: +### Immediate + +Immediate execution means that the data source is read and the operation is performed once. All the standard query operators that return a scalar result execute immediately. Examples of such queries are `Count`, `Max`, `Average`, and `First`. These methods execute without an explicit `foreach` statement because the query itself must use `foreach` in order to return a result. These queries return a single value, not an `IEnumerable` collection. You can force *any* query to execute immediately using the or methods. Immediate execution provides reuse of query results, not query declaration. The results are retrieved once, then stored for future use. The following query returns a count of the even numbers in the source array: + +:::code language="csharp" source="./snippets/SnippetApp/Program.cs" id="EagerEvaluation"::: + +To force immediate execution of any query and cache its results, you can call the or methods. + +:::code language="csharp" source="./snippets/SnippetApp/Program.cs" id="MoreEagerEvaluation"::: + +You can also force execution by putting the `foreach` loop immediately after the query expression. However, by calling `ToList` or `ToArray` you also cache all the data in a single collection object. + +### Deferred + +Deferred execution means that the operation isn't performed at the point in the code where the query is declared. The operation is performed only when the query variable is enumerated, for example by using a `foreach` statement. The results of executing the query depend on the contents of the data source when the query is executed rather than when the query is defined. If the query variable is enumerated multiple times, the results might differ every time. Almost all the standard query operators whose return type is or execute in a deferred manner. Deferred execution provides the facility of query reuse since the query fetches the updated data from the data source each time query results are iterated. The following code shows an example of deferred execution: :::code language="csharp" source="./snippets/SnippetApp/Program.cs" id="QueryExecution"::: The `foreach` statement is also where the query results are retrieved. For example, in the previous query, the iteration variable `num` holds each value (one at a time) in the returned sequence. -Because the query variable itself never holds the query results, you can execute it repeatedly to retrieve updated data. For example, you might have a database that is being updated continually by a separate application. In your application, you could create one query that retrieves the latest data, and you could execute it at intervals to retrieve updated results. +Because the query variable itself never holds the query results, you can execute it repeatedly to retrieve updated data. For example, a separate application might update a database continually. In *your* application, you could create one query that retrieves the latest data, and you could execute it at intervals to retrieve updated results. -### Forcing Immediate Execution +Query operators that use deferred execution can be additionally classified as streaming or nonstreaming. -Queries that perform aggregation functions over a range of source elements must first iterate over those elements. Examples of such queries are `Count`, `Max`, `Average`, and `First`. These methods execute without an explicit `foreach` statement because the query itself must use `foreach` in order to return a result. These queries return a single value, not an `IEnumerable` collection. The following query returns a count of the even numbers in the source array: +### Streaming -:::code language="csharp" source="./snippets/SnippetApp/Program.cs" id="EagerEvaluation"::: +Streaming operators don't have to read all the source data before they yield elements. At the time of execution, a streaming operator performs its operation on each source element as it is read and yields the element if appropriate. A streaming operator continues to read source elements until a result element can be produced. This means that more than one source element might be read to produce one result element. -To force immediate execution of any query and cache its results, you can call the or methods. +### Nonstreaming -:::code language="csharp" source="./snippets/SnippetApp/Program.cs" id="MoreEagerEvaluation"::: +Nonstreaming operators must read all the source data before they can yield a result element. Operations such as sorting or grouping fall into this category. At the time of execution, nonstreaming query operators read all the source data, put it into a data structure, perform the operation, and yield the resulting elements. -You can also force execution by putting the `foreach` loop immediately after the query expression. However, by calling `ToList` or `ToArray` you also cache all the data in a single collection object. +## Classification table + +The following table classifies each standard query operator method according to its method of execution. + +> [!NOTE] +> If an operator is marked in two columns, two input sequences are involved in the operation, and each sequence is evaluated differently. In these cases, it is always the first sequence in the parameter list that is evaluated in a deferred, streaming manner. + +| Standard query operator | Return type | Immediate execution | Deferred streaming execution | Deferred nonstreaming execution | +|-----------------------------------------------------|-------------|---------------------|------------------------------|----------------------------------| +| | `TSource` | X | | | +| | | X | | | +| | | X | | | +| | | | X | | +| | Single numeric value | X | | | +| | | | X | | +| | | | X | | +| | | X | | | +| | | X | | | +| | | | X | | +| | | | X | | +| | `TSource` | X | | | +| | `TSource?` | X | | | +| | | X | | | +| | | | X | X | +| | `TSource` | X | | | +| | `TSource?` | X | | | +| | | | | X | +| | | | X | X | +| | | | X | X | +| | | | X | X | +| | `TSource` | X | | | +| | `TSource?` | X | | | +| | | X | | | +| | Single numeric value, `TSource`, or `TResult?` | X | | | +| | Single numeric value, `TSource`, or `TResult?` | X | | | +| | | | X | | +| | | | | X | +| | | | | X | +| | | | X | | +| | | | X | | +| | | | | X | +| | | | X | | +| | | | X | | +| | | X | | | +| | `TSource` | X | | | +| | `TSource?` | X | | | +| | | | X | | +| | | | X | | +| | Single numeric value | X | | | +| | | | X | | +| | | | X | | +| | | | | X | +| | | | | X | +| | `TSource[]` array | X | | | +| | | X | | | +| | | X | | | +| | | X | | | +| | | | X | | +| | | | X | | + +## LINQ to objects + +"LINQ to Objects" refers to the use of LINQ queries with any or collection directly. You can use LINQ to query any enumerable collections, such as , , or . The collection can be user-defined or a type returned by a .NET API. In the LINQ approach, you write declarative code that describes what you want to retrieve. LINQ to Objects provides a great introduction to programming with LINQ. + +LINQ queries offer three main advantages over traditional `foreach` loops: + +- They're more concise and readable, especially when filtering multiple conditions. +- They provide powerful filtering, ordering, and grouping capabilities with a minimum of application code. +- They can be ported to other data sources with little or no modification. + +The more complex the operation you want to perform on the data, the more benefit you realize using LINQ instead of traditional iteration techniques. + +## Store the results of a query in memory + +A query is basically a set of instructions for how to retrieve and organize data. Queries are executed lazily, as each subsequent item in the result is requested. When you use `foreach` to iterate the results, items are returned as accessed. To evaluate a query and store its results without executing a `foreach` loop, just call one of the following methods on the query variable: + +- +- +- +- + +You should assign the returned collection object to a new variable when you store the query results, as shown in the following example: + +:::code language="csharp" source="./snippets/SnippetApp/StoreResultsOfQueryInMemory.cs" id="store_results_of_query_in_memory_1"::: ## See also -- [Walkthrough: Writing Queries in C#](../../programming-guide/concepts/linq//walkthrough-writing-queries-linq.md) +- [Walkthrough: Writing Queries in C#](walkthrough-writing-queries-linq.md) - [foreach, in](../../language-reference/statements/iteration-statements.md#the-foreach-statement) - [Query Keywords (LINQ)](../../language-reference/keywords/query-keywords.md) diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/DataClasses.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/DataClasses.cs similarity index 100% rename from samples/snippets/csharp/concepts/linq/LinqSamples/DataClasses.cs rename to docs/csharp/linq/get-started/snippets/SnippetApp/DataClasses.cs diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/Exceptions.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/Exceptions.cs similarity index 100% rename from samples/snippets/csharp/concepts/linq/LinqSamples/Exceptions.cs rename to docs/csharp/linq/get-started/snippets/SnippetApp/Exceptions.cs diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/NullValues.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/NullValues.cs similarity index 100% rename from samples/snippets/csharp/concepts/linq/LinqSamples/NullValues.cs rename to docs/csharp/linq/get-started/snippets/SnippetApp/NullValues.cs diff --git a/docs/csharp/linq/get-started/snippets/SnippetApp/Program.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/Program.cs index acaf8775ee394..b38cb84a5047e 100644 --- a/docs/csharp/linq/get-started/snippets/SnippetApp/Program.cs +++ b/docs/csharp/linq/get-started/snippets/SnippetApp/Program.cs @@ -66,6 +66,20 @@ WriteSeparator(nameof(Linq.GetStarted.TypeRelationships.ImplicitType)); Linq.GetStarted.TypeRelationships.ImplicitType(); +WriteSeparator(nameof(Linq.GetStarted.TypeRelationships.ImplicitType)); +LinqSamples.ReturnQueryFromMethod.ReturnQueryFromMethod1(); + +WriteSeparator(nameof(LinqSamples.RuntimeFiltering)); +LinqSamples.RuntimeFiltering.RuntimeFiltering1(); +LinqSamples.RuntimeFiltering.RuntimeFiltering2(); + +WriteSeparator(nameof(LinqSamples.NullValues)); +LinqSamples.NullValues.NullValues1(); + +WriteSeparator(nameof(LinqSamples.Exceptions)); +LinqSamples.Exceptions.Exceptions1(); +LinqSamples.Exceptions.Exceptions2(); + void WriteSeparator(string symbol) => Console.WriteLine($"========== {symbol} =========="); // This won't work, but we want to make sure it compiles. diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/ReturnQueryFromMethod.cs similarity index 100% rename from samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs rename to docs/csharp/linq/get-started/snippets/SnippetApp/ReturnQueryFromMethod.cs diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/RuntimeFiltering.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/RuntimeFiltering.cs similarity index 100% rename from samples/snippets/csharp/concepts/linq/LinqSamples/RuntimeFiltering.cs rename to docs/csharp/linq/get-started/snippets/SnippetApp/RuntimeFiltering.cs diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/StoreResultsOfQueryInMemory.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/StoreResultsOfQueryInMemory.cs similarity index 100% rename from samples/snippets/csharp/concepts/linq/LinqSamples/StoreResultsOfQueryInMemory.cs rename to docs/csharp/linq/get-started/snippets/SnippetApp/StoreResultsOfQueryInMemory.cs diff --git a/docs/csharp/linq/get-started/snippets/SnippetApp/how-to-handle-null-values-in-query-expressions_2.cs b/docs/csharp/linq/get-started/snippets/SnippetApp/how-to-handle-null-values-in-query-expressions_2.cs new file mode 100644 index 0000000000000..5f282702bb03e --- /dev/null +++ b/docs/csharp/linq/get-started/snippets/SnippetApp/how-to-handle-null-values-in-query-expressions_2.cs @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/Program.cs b/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/Program.cs new file mode 100644 index 0000000000000..ec723d730b08d --- /dev/null +++ b/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/Program.cs @@ -0,0 +1,290 @@ +// +using WalkthroughWritingLinqQueries; + +// Create a data source by using a collection initializer. +IEnumerable students = +[ + new Student(First: "Svetlana", Last: "Omelchenko", ID: 111, Scores: [97, 92, 81, 60]), + new Student(First: "Claire", Last: "O'Donnell", ID: 112, Scores: [75, 84, 91, 39]), + new Student(First: "Sven", Last: "Mortensen", ID: 113, Scores: [88, 94, 65, 91]), + new Student(First: "Cesar", Last: "Garcia", ID: 114, Scores: [97, 89, 85, 82]), + new Student(First: "Debra", Last: "Garcia", ID: 115, Scores: [35, 72, 91, 70]), + new Student(First: "Fadi", Last: "Fakhouri", ID: 116, Scores: [99, 86, 90, 94]), + new Student(First: "Hanying", Last: "Feng", ID: 117, Scores: [93, 92, 80, 87]), + new Student(First: "Hugo", Last: "Garcia", ID: 118, Scores: [92, 90, 83, 78]), + + new Student("Lance", "Tucker", 119, [68, 79, 88, 92]), + new Student("Terry", "Adams", 120, [99, 82, 81, 79]), + new Student("Eugene", "Zabokritski", 121, [96, 85, 91, 60]), + new Student("Michael", "Tucker", 122, [94, 92, 91, 91]) +]; +// + +// +// Create the query. +// The first line could also be written as "var studentQuery =" +IEnumerable studentQuery = + from student in students + where student.Scores[0] > 90 + select student; +// + +Console.WriteLine("\nRunning Query 1............."); +// +// Execute the query. +// var could be used here also. +foreach (Student student in studentQuery) +{ + Console.WriteLine($"{student.Last}, {student.First}"); +} + +// Output: +// Omelchenko, Svetlana +// Garcia, Cesar +// Fakhouri, Fadi +// Feng, Hanying +// Garcia, Hugo +// Adams, Terry +// Zabokritski, Eugene +// Tucker, Michael +// + +Console.WriteLine("\nRunning OrderBy Query............."); +OrderByQuery(); + +Console.WriteLine("\nRunning Group Query............."); +GroupQuery(); + +Console.WriteLine("\nRunning Group Var Query............."); +GroupVarQuery(); + +Console.WriteLine("\nRunning Ordered Group Query............."); +OrderedGroupQuery(); + +Console.WriteLine("\nRunning Group Query With Let............."); +QueryWithLetVariable(); + +Console.WriteLine("\nRunning Compute Average............."); +ComputeAverage(); + +Console.WriteLine("\nRunning Select projection............."); +SelectProjection(); + +void OrderByQuery() +{ + // Create the query. + // The first line could also be written as "var studentQuery =" + IEnumerable studentQuery = + from student in students + where student.Scores[0] > 90 + // + orderby student.Last ascending + // + // + orderby student.Scores[0] descending + // + select student; + + Console.WriteLine("\nRunning Query 1............."); + // Execute the query. + // var could be used here also. + foreach (Student student in studentQuery) + { + // + Console.WriteLine($"{student.Last}, {student.First} {student.Scores[0]}"); + // + } +} + +void GroupQuery() +{ + // + IEnumerable> studentQuery = + from student in students + group student by student.Last[0]; + // + + // + foreach (IGrouping studentGroup in studentQuery) + { + Console.WriteLine(studentGroup.Key); + foreach (Student student in studentGroup) + { + Console.WriteLine($" {student.Last}, {student.First}"); + } + } + // Output: + // O + // Omelchenko, Svetlana + // O'Donnell, Claire + // M + // Mortensen, Sven + // G + // Garcia, Cesar + // Garcia, Debra + // Garcia, Hugo + // F + // Fakhouri, Fadi + // Feng, Hanying + // T + // Tucker, Lance + // Tucker, Michael + // A + // Adams, Terry + // Z + // Zabokritski, Eugene + // +} + +void GroupVarQuery() +{ + // + IEnumerable> studentQuery = + from student in students + group student by student.Last[0]; + + foreach (IGrouping studentGroup in studentQuery) + { + Console.WriteLine(studentGroup.Key); + foreach (Student student in studentGroup) + { + Console.WriteLine($" {student.Last}, {student.First}"); + } + } + // +} + +void OrderedGroupQuery() +{ + // + var studentQuery4 = + from student in students + group student by student.Last[0] into studentGroup + orderby studentGroup.Key + select studentGroup; + + foreach (var groupOfStudents in studentQuery4) + { + Console.WriteLine(groupOfStudents.Key); + foreach (var student in groupOfStudents) + { + Console.WriteLine($" {student.Last}, {student.First}"); + } + } + + // Output: + //A + // Adams, Terry + //F + // Fakhouri, Fadi + // Feng, Hanying + //G + // Garcia, Cesar + // Garcia, Debra + // Garcia, Hugo + //M + // Mortensen, Sven + //O + // Omelchenko, Svetlana + // O'Donnell, Claire + //T + // Tucker, Lance + // Tucker, Michael + //Z + // Zabokritski, Eugene + // +} + +void QueryWithLetVariable() +{ + // + // This query returns those students whose + // first test score was higher than their + // average score. + var studentQuery5 = + from student in students + let totalScore = student.Scores[0] + student.Scores[1] + + student.Scores[2] + student.Scores[3] + where totalScore / 4 < student.Scores[0] + select $"{student.Last}, {student.First}"; + + foreach (string s in studentQuery5) + { + Console.WriteLine(s); + } + + // Output: + // Omelchenko, Svetlana + // O'Donnell, Claire + // Mortensen, Sven + // Garcia, Cesar + // Fakhouri, Fadi + // Feng, Hanying + // Garcia, Hugo + // Adams, Terry + // Zabokritski, Eugene + // Tucker, Michael + // +} + +void ComputeAverage() +{ + // + var studentQuery = + from student in students + let totalScore = student.Scores[0] + student.Scores[1] + + student.Scores[2] + student.Scores[3] + select totalScore; + + double averageScore = studentQuery.Average(); + Console.WriteLine("Class average score = {0}", averageScore); + + // Output: + // Class average score = 334.166666666667 + // + + // + var aboveAverageQuery = + from student in students + let x = student.Scores[0] + student.Scores[1] + + student.Scores[2] + student.Scores[3] + where x > averageScore + select new { id = student.ID, score = x }; + + foreach (var item in aboveAverageQuery) + { + Console.WriteLine("Student ID: {0}, Score: {1}", item.id, item.score); + } + + // Output: + // Student ID: 113, Score: 338 + // Student ID: 114, Score: 353 + // Student ID: 116, Score: 369 + // Student ID: 117, Score: 352 + // Student ID: 118, Score: 343 + // Student ID: 120, Score: 341 + // Student ID: 122, Score: 368 + // +} + +void SelectProjection() +{ + // + IEnumerable studentQuery = + from student in students + where student.Last == "Garcia" + select student.First; + + Console.WriteLine("The Garcias in the class are:"); + foreach (string s in studentQuery) + { + Console.WriteLine(s); + } + + // Output: + // The Garcias in the class are: + // Cesar + // Debra + // Hugo + // +} diff --git a/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/StudentDataSource.cs b/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/StudentDataSource.cs new file mode 100644 index 0000000000000..4ba916ade6957 --- /dev/null +++ b/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/StudentDataSource.cs @@ -0,0 +1,3 @@ +namespace WalkthroughWritingLinqQueries; + +public record Student(string First, string Last, int ID, int[] Scores); diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/GettingStarted.csproj b/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/WalkthroughWritingLinqQueries.csproj similarity index 68% rename from samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/GettingStarted.csproj rename to docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/WalkthroughWritingLinqQueries.csproj index 705a3652a728c..2150e3797ba5e 100644 --- a/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/GettingStarted.csproj +++ b/docs/csharp/linq/get-started/snippets/WalkthroughWritingLinqQueries/WalkthroughWritingLinqQueries.csproj @@ -3,7 +3,8 @@ Exe net8.0 - - LINQGettingStarted_1.Program + enable + enable + diff --git a/docs/csharp/linq/get-started/walkthrough-writing-queries-linq.md b/docs/csharp/linq/get-started/walkthrough-writing-queries-linq.md new file mode 100644 index 0000000000000..e7e92cb2ce379 --- /dev/null +++ b/docs/csharp/linq/get-started/walkthrough-writing-queries-linq.md @@ -0,0 +1,137 @@ +--- +title: "Tutorial: Writing LINQ Queries in C#" +description: This walkthrough shows how C# language features are used in LINQ query expressions. +ms.date: 04/22/2024 +ms.topic: tutorial +helpviewer_keywords: + - "LINQ [C#], walkthroughs" + - "LINQ [C#], writing queries" + - "queries [LINQ in C#], writing" + - "writing LINQ queries" +--- +# Tutorial: Write queries in C# using language integrated query (LINQ) + +In this tutorial, you create a data source and write several LINQ queries. You can experiment with the query expressions and see the differences in the results. This walkthrough demonstrates the C# language features that are used to write LINQ query expressions. You can follow along and build the app and experiment with the queries yourself. This article assumes you've installed the latest .NET SDK. If not, go to the [.NET Downloads page](https://dot.net) and install the latest version on your machine. + +First, create the application. From the console, type the following command: + +```dotnetcli +dotnet new console -o WalkthroughWritingLinqQueries +``` + +Or, if you prefer Visual Studio, create a new console application named *WalkthroughWritingLinqQueries*. + +## Create an in-memory data source + +The first step is to create a data source for your queries. The data source for the queries is a simple list of `Student` records. Each `Student` record has a first name, family name, and an array of integers that represents their test scores in the class. Add a new file named *students.cs*, and copy the following code into that file: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/StudentDataSource.cs"::: + +Note the following characteristics: + +- The `Student` record consists of autoimplemented properties. +- Each student in the list is initialized with the primary constructor. +- The sequence of scores for each student is initialized with a primary constructor. + +Next, create a sequence of `Student` records that serves as the source of this query. Open *Program.cs*, and remove the following boilerplate code: + +```csharp +// See https://aka.ms/new-console-template for more information +Console.WriteLine("Hello, World!"); +``` + +Replace it with the following code that creates a sequence of `Student` records: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="CreateSequence"::: + +- The sequence of students is initialized with a collection expression. +- The `Student` record type holds the static list of all students. +- Some of the constructor calls use [named arguments](../../programming-guide/classes-and-structs/named-and-optional-arguments.md) to clarify which argument matches which constructor parameter. + +Try adding a few more students with different test scores to the list of students to get more familiar with the code so far. + +## Create the query + +Next, you create your first query. Your query, when you execute it, produces a list of all students whose score on the first test was greater than 90. Because the whole `Student` object is selected, the type of the query is `IEnumerable`. Although the code could also use implicit typing by using the [var](../../language-reference/statements/declarations.md#implicitly-typed-local-variables) keyword, explicit typing is used to clearly illustrate results. (For more information about `var`, see [Implicitly Typed Local Variables](../../programming-guide/classes-and-structs/implicitly-typed-local-variables.md).) Add the following code to *Program.cs*, after the code that creates the sequence of students: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="DefineFirstQuery"::: + +The query's range variable, `student`, serves as a reference to each `Student` in the source, providing member access for each object. + +## Run the query + +Now write the `foreach` loop that causes the query to execute. Each element in the returned sequence is accessed through the iteration variable in the `foreach` loop. The type of this variable is `Student`, and the type of the query variable is compatible, `IEnumerable`. After you added the following code, build and run the application to see the results in the **Console** window. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="RunFirstQuery"::: + +To further refine the query, you can combine multiple Boolean conditions in the `where` clause. The following code adds a condition so that the query returns those students whose first score was over 90 and whose last score was less than 80. The `where` clause should resemble the following code. + +```csharp +where student.Scores[0] > 90 && student.Scores[3] < 80 +``` + +Try the preceding `where` clause, or experiment yourself with other filter conditions. For more information, see [where clause](../../language-reference/keywords/where-clause.md). + +## Order the query results + +It's easier to scan the results if they are in some kind of order. You can order the returned sequence by any accessible field in the source elements. For example, the following `orderby` clause orders the results in alphabetical order from A to Z according to the family name of each student. Add the following `orderby` clause to your query, right after the `where` statement and before the `select` statement: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="OrderByLast"::: + +Now change the `orderby` clause so that it orders the results in reverse order according to the score on the first test, from the highest score to the lowest score. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="OrderByScore"::: + +Change the `WriteLine` format string so that you can see the scores: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="WriteFirstScore"::: + +For more information, see [orderby clause](../../language-reference/keywords/orderby-clause.md). + +## Group the results + +Grouping is a powerful capability in query expressions. A query with a group clause produces a sequence of groups, and each group itself contains a `Key` and a sequence that consists of all the members of that group. The following new query groups the students by using the first letter of their family name as the key. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="CreateGroupQuery"::: + +The type of the query changed. It now produces a sequence of groups that have a `char` type as a key, and a sequence of `Student` objects. The code in the `foreach` execution loop also must change: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="RunGroupQuery"::: + +Run the application and view the results in the **Console** window. For more information, see [group clause](../../language-reference/keywords/group-clause.md). + +Explicitly coding `IEnumerables` of `IGroupings` can quickly become tedious. Write the same query and `foreach` loop much more conveniently by using `var`. The `var` keyword doesn't change the types of your objects; it just instructs the compiler to infer the types. Change the type of `studentQuery` and the iteration variable `group` to `var` and rerun the query. In the inner `foreach` loop, the iteration variable is still typed as `Student`, and the query works as before. Change the `student` iteration variable to `var` and run the query again. You see that you get exactly the same results. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="VarGroupQuery"::: + +For more information about `var`, see [Implicitly Typed Local Variables](../../programming-guide/classes-and-structs/implicitly-typed-local-variables.md). + +## Order the groups by their key value + +The groups in the previous query aren't in alphabetical order. You can provide an `orderby` clause after the `group` clause. But to use an `orderby` clause, you first need an identifier that serves as a reference to the groups created by the `group` clause. You provide the identifier by using the `into` keyword, as follows: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="OrderedGroupQuery"::: + +Run this query, and the groups are now sorted in alphabetical order. + +You can use the `let` keyword to introduce an identifier for any expression result in the query expression. This identifier can be a convenience, as in the following example. It can also enhance performance by storing the results of an expression so that it doesn't have to be calculated multiple times. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="QueryWithLet"::: + +For more information, see the article on the [`let` clause](../../language-reference/keywords/let-clause.md). + +## Use method syntax in a query expression + +As described in [Query Syntax and Method Syntax in LINQ](./write-linq-queries.md), some query operations can only be expressed by using method syntax. The following code calculates the total score for each `Student` in the source sequence, and then calls the `Average()` method on the results of that query to calculate the average score of the class. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="ComputeAverage"::: + +## To transform or project in the select clause + +It's common for a query to produce a sequence whose elements differ from the elements in the source sequences. Delete or comment out your previous query and execution loop, and replace it with the following code. The query returns a sequence of strings (not `Students`), and this fact is reflected in the `foreach` loop. + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="SelectProjection"::: + +Code earlier in this walkthrough indicated that the average class score is approximately 334. To produce a sequence of `Students` whose total score is greater than the class average, together with their `Student ID`, you can use an anonymous type in the `select` statement: + +:::code language="csharp" source="./snippets/WalkthroughWritingLinqQueries/Program.cs" id="BetterThanMost"::: diff --git a/docs/csharp/linq/get-started/write-linq-queries.md b/docs/csharp/linq/get-started/write-linq-queries.md index 86deb1664c96c..ac0a9376e19cb 100644 --- a/docs/csharp/linq/get-started/write-linq-queries.md +++ b/docs/csharp/linq/get-started/write-linq-queries.md @@ -1,7 +1,7 @@ --- title: Use C# to write LINQ queries description: Learn how to write LINQ queries in C#. -ms.date: 12/14/2023 +ms.date: 04/19/2024 --- # Write C# LINQ queries to query data @@ -21,7 +21,7 @@ To understand the method-based query, let's examine it more closely. On the righ ![Screenshot showing all the standard query operators in Intellisense.](./media/write-linq-queries/standard-query-operators.png) -Although it looks as if includes additional methods, it doesn't. The standard query operators are implemented as *extension methods*. Extensions methods "extend" an existing type; they can be called as if they were instance methods on the type. The standard query operators extend and that is why you can write `numbers.Where(...)`. +Although it looks as if includes more methods, it doesn't. The standard query operators are implemented as *extension methods*. Extensions methods "extend" an existing type; they can be called as if they were instance methods on the type. The standard query operators extend and that is why you can write `numbers.Where(...)`. To use extension methods, you bring them into scope with `using` directives. From your application's point of view, an extension method and a regular instance method are the same. @@ -90,7 +90,62 @@ It can be written by using explicit typing, as follows: :::code language="csharp" source="./snippets/SnippetApp/WriteLinqQueries.cs" id="write_linq_queries_5b"::: +## Dynamically specify predicate filters at run time + +In some cases, you don't know until run time how many predicates you have to apply to source elements in the `where` clause. One way to dynamically specify multiple predicate filters is to use the method, as shown in the following example. The query returns different results based on the value of `id` when the query is executed. + +:::code language="csharp" source="./snippets/SnippetApp/RuntimeFiltering.cs" id="runtime_filtering_1"::: + +You can use control flow statements, such as `if... else` or `switch`, to select among predetermined alternative queries. In the following example, `studentQuery` uses a different `where` clause if the run-time value of `oddYear` is `true` or `false`. + +:::code language="csharp" source="./snippets/SnippetApp/RuntimeFiltering.cs" id="runtime_filtering_2"::: + +## Handle null values in query expressions + +This example shows how to handle possible null values in source collections. An object collection such as an can contain elements whose value is [null](../../language-reference/keywords/null.md). If a source collection is `null` or contains an element whose value is `null`, and your query doesn't handle `null` values, a is thrown when you execute the query. + +You can code defensively to avoid a null reference exception as shown in the following example: + +:::code language="csharp" source="./snippets/SnippetApp/NullValues.cs" id="null_values_1"::: + +In the previous example, the `where` clause filters out all null elements in the categories sequence. This technique is independent of the null check in the join clause. The conditional expression with null in this example works because `Products.CategoryID` is of type `int?`, which is shorthand for `Nullable`. + +In a join clause, if only one of the comparison keys is a nullable value type, you can cast the other to a nullable value type in the query expression. In the following example, assume that `EmployeeID` is a column that contains values of type `int?`: + +```csharp +var query = + from o in db.Orders + join e in db.Employees + on o.EmployeeID equals (int?)e.EmployeeID + select new { o.OrderID, e.FirstName }; +``` + +In each of the examples, the `equals` query keyword is used. You can also use [pattern matching](../../language-reference/operators/patterns.md), which includes patterns for `is null` and `is not null`. These patterns aren't recommended in LINQ queries because query providers might not interpret the new C# syntax correctly. A query provider is a library that translates C# query expressions into a native data format, such as Entity Framework Core. Query providers implement the interface to create data sources that implement the interface. + +## Handle exceptions in query expressions + +It's possible to call any method in the context of a query expression. Don't call any method in a query expression that can create a side effect such as modifying the contents of the data source or throwing an exception. This example shows how to avoid raising exceptions when you call methods in a query expression without violating the general .NET guidelines on exception handling. Those guidelines state that it's acceptable to catch a specific exception when you understand why it's thrown in a given context. For more information, see [Best Practices for Exceptions](../../../standard/exceptions/best-practices-for-exceptions.md). + +The final example shows how to handle those cases when you must throw an exception during execution of a query. + +The following example shows how to move exception handling code outside a query expression. This refactoring is only possible when the method doesn't depend on any variables local to the query. It's easier to deal with exceptions outside of the query expression. + +:::code language="csharp" source="./snippets/SnippetApp/Exceptions.cs" id="exceptions_1"::: + +In the `catch (InvalidOperationException)` block in the preceding example, handle (or don't handle) the exception in the way that is appropriate for your application. + +In some cases, the best response to an exception that is thrown from within a query might be to stop the query execution immediately. The following example shows how to handle exceptions that might be thrown from inside a query body. Assume that `SomeMethodThatMightThrow` can potentially cause an exception that requires the query execution to stop. + +The `try` block encloses the `foreach` loop, and not the query itself. The `foreach` loop is the point at which the query is executed. Run-time exceptions are thrown when the query is executed. Therefore they must be handled in the `foreach` loop. + +:::code language="csharp" source="./snippets/SnippetApp/Exceptions.cs" id="exceptions_2"::: + +Remember to catch whatever exception you expect to raise and/or do any necessary cleanup in a `finally` block. + ## See also -- [Walkthrough: Writing Queries in C#](../../programming-guide/concepts/linq/walkthrough-writing-queries-linq.md) +- [Walkthrough: Writing Queries in C#](walkthrough-writing-queries-linq.md) - [where clause](../../language-reference/keywords/where-clause.md) +- [Querying based on runtime state](../../advanced-topics/expression-trees/debugview-syntax.md) +- +- [Nullable value types](../../language-reference/builtin-types/nullable-value-types.md) diff --git a/docs/csharp/linq/group-results-by-contiguous-keys.md b/docs/csharp/linq/group-results-by-contiguous-keys.md deleted file mode 100644 index e005a81610640..0000000000000 --- a/docs/csharp/linq/group-results-by-contiguous-keys.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Group results by contiguous keys (LINQ in C#) -description: How to group results by contiguous keys using LINQ in C#. -ms.date: 01/23/2024 ---- -# Group results by contiguous keys - -The following example shows how to group elements into chunks that represent subsequences of contiguous keys. For example, assume that you are given the following sequence of key-value pairs: - -|Key|Value| -|---------|-----------| -|A|We| -|A|think| -|A|that| -|B|Linq| -|C|is| -|A|really| -|B|cool| -|B|!| - -The following groups will be created in this order: - -1. We, think, that -1. Linq -1. is -1. really -1. cool, ! - -The solution is implemented as an extension method that is thread-safe and that returns its results in a streaming manner. In other words, it produces its groups as it moves through the source sequence. Unlike the `group` or `orderby` operators, it can begin returning groups to the caller before all of the sequence has been read. - -Thread-safety is accomplished by making a copy of each group or chunk as the source sequence is iterated, as explained in the source code comments. If the source sequence has a large sequence of contiguous items, the common language runtime may throw an . - -## Example - -The following example shows both the extension method and the client code that uses it: - -:::code language="csharp" source="./snippets/linq-index/GroupByContiguousKeys.cs" id="group_by_contiguous_keys_chunkextensions"::: - -:::code language="csharp" source="./snippets/linq-index/GroupByContiguousKeys.cs" id="group_by_contiguous_keys_client_code"::: - -### `ChunkExtensions` class - -In the presented code, of `ChunkExtensions` class implementation, the `while(true)`, loop in the `ChunkBy` method, iterates through source sequence and create a copy of each Chunk. On each pass, the iterator advances to the first element of the next "Chunk" -
(The chunk is represented by [`Chunk`](#chunk-class) class.) -
in the source sequence. This loop corresponds to the outer foreach loop that executes the query. -What happens in that loop is: - -1. Get the key for the current Chunk, by assigning it to `key` variable: `var key = keySelector(enumerator.Current);`. The source iterator will churn through the source sequence until it finds an element with a key that doesn't match. -1. Make a new Chunk (group) object, and store it in `current` variable, that initially has one GroupItem, which is a copy of the current source element. -1. Return that Chunk. A Chunk is an `IGrouping`, which is the return value of the [`ChunkBy`](#chunk-class) method. At this point the Chunk only has the first element in its source sequence. The remaining elements will be returned only when the client code foreach's over this chunk. See `Chunk.GetEnumerator` for more info. -1. Check to see whether -
(a) the chunk has made a copy of all its source elements or -
(b) the iterator has reached the end of the source sequence. -
If the caller uses an inner foreach loop to iterate the chunk items, and that loop ran to completion, then the `Chunk.GetEnumerator` method will already have made copies of all chunk items before we get here. If the `Chunk.GetEnumerator` loop did not enumerate all elements in the chunk, we need to do it here to avoid corrupting the iterator for clients that may be calling us on a separate thread. - -### `Chunk` class - -The `Chunk` class is a contiguous group of one or more source elements that have the same key. A Chunk has a key and a list of ChunkItem objects, which are copies of the elements in the source sequence: - -:::code language="csharp" source="./snippets/linq-index/GroupByContiguousKeys.cs" id="group_by_contiguous_keys_chunk_class"::: - -A Chunk has a linked list of `ChunkItem`s, which represent the elements in the current chunk. Each `ChunkItem` (represented by `ChunkItem` class) has a reference to the next `ChunkItem` in the list. -The list consists of it's `head` - which stores the contents of the first source element that belongs with this chunk, and it's `tail` - which is an end of the list. It is repositioned each time a new `ChunkItem` is added. -
The `Chunk` class contains the private boolean field: `DoneCopyingChunk`, which indicates that all chunk elements have been copied to the list of ChunkItems, and the source enumerator is either at the end, or else on an element with a new key. -The tail of the linked list is set to `null` in the `CopyNextChunkElement` method if the key of the next element does not match the current chunk's key, or there are no more elements in the source. - -The `CopyNextChunkElement` method of the `Chunk` class adds one `ChunkItem` to the current group of items. -
By using `enumerator.MoveNext()` method, it tries to advance the iterator on the source sequence. If `MoveNext()` method returns `false` it means that iteration is at the end, and `isLastSourceElement` is set to `true`. -Then, if iteration is at the end of the source, or at the end of the current chunk then the `enumerator` and `predicate` is null out for reuse with the next chunk. - -The `CopyAllChunkElements` method is called after the end of the last chunk was reached. It first checks whether there are more elements in the source sequence. If there are, it returns `true` if enumerator for this chunk was exhausted. In this method, when private `DoneCopyingChunk` field is checked for `true`, if isLastSourceElement is `false`, it signals to the outer iterator to continue iterating. - -The `GetEnumerator` method of the `Chunk` class is invoked by the inner foreach loop. This method stays just one step ahead of the client requests. It adds the next element of the chunk only after the clients requests the last element in the list so far. diff --git a/docs/csharp/linq/handle-exceptions-in-query-expressions.md b/docs/csharp/linq/handle-exceptions-in-query-expressions.md deleted file mode 100644 index 950c8c99a9bcd..0000000000000 --- a/docs/csharp/linq/handle-exceptions-in-query-expressions.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Handle exceptions in query expressions (LINQ in C#) -description: Learn how to handle exceptions in LINQ query expressions in C#. -ms.date: 12/01/2016 -ms.assetid: 2bf0c397-13fb-4f68-bc2b-531c6c88a167 ---- -# Handle exceptions in query expressions - -It's possible to call any method in the context of a query expression. However, we recommend that you avoid calling any method in a query expression that can create a side effect such as modifying the contents of the data source or throwing an exception. This example shows how to avoid raising exceptions when you call methods in a query expression without violating the general .NET guidelines on exception handling. Those guidelines state that it's acceptable to catch a specific exception when you understand why it's thrown in a given context. For more information, see [Best Practices for Exceptions](../../standard/exceptions/best-practices-for-exceptions.md). - -The final example shows how to handle those cases when you must throw an exception during execution of a query. - -## Example 1 - -The following example shows how to move exception handling code outside a query expression. This is only possible when the method does not depend on any variables local to the query. It is easier to deal with exceptions outside of the query expression. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/Exceptions.cs" id="exceptions_1"::: - -Note that in the `catch (InvalidOperationException)` in the example above, handle (or don't handle) the exception in the way that is appropriate for your application. - -## Example 2 - -In some cases, the best response to an exception that is thrown from within a query might be to stop the query execution immediately. The following example shows how to handle exceptions that might be thrown from inside a query body. Assume that `SomeMethodThatMightThrow` can potentially cause an exception that requires the query execution to stop. - -Note that the `try` block encloses the `foreach` loop, and not the query itself. This is because the `foreach` loop is the point at which the query is actually executed. For more information, see [Introduction to LINQ queries](get-started/introduction-to-linq-queries.md). -The runtime exception will only be thrown when the query is executed. -Therefore they must be handled in the `foreach` loop. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/Exceptions.cs" id="exceptions_2"::: - -Remember to catch whatever exception you expect to raise and/or do any necessary cleanup in a finally block. - -## See also - -- [Language Integrated Query (LINQ)](index.md) diff --git a/docs/csharp/linq/handle-null-values-in-query-expressions.md b/docs/csharp/linq/handle-null-values-in-query-expressions.md deleted file mode 100644 index 133efc1ba1fd2..0000000000000 --- a/docs/csharp/linq/handle-null-values-in-query-expressions.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Handle null values in query expressions (LINQ in C#) -description: Learn how to handle null values in LINQ query expressions in C#. -ms.date: 04/29/2021 -ms.assetid: ac63ae8b-724d-4251-9334-528f4e884ae7 ---- -# Handle null values in query expressions - -This example shows how to handle possible null values in source collections. An object collection such as an can contain elements whose value is [null](../language-reference/keywords/null.md). If a source collection is `null` or contains an element whose value is `null`, and your query doesn't handle `null` values, a will be thrown when you execute the query. - -You can code defensively to avoid a null reference exception as shown in the following example: - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/NullValues.cs" id="null_values_1"::: - -In the previous example, the `where` clause filters out all null elements in the categories sequence. This technique is independent of the null check in the join clause. The conditional expression with null in this example works because `Products.CategoryID` is of type `int?`, which is shorthand for `Nullable`. - -In a join clause, if only one of the comparison keys is a nullable value type, you can cast the other to a nullable value type in the query expression. In the following example, assume that `EmployeeID` is a column that contains values of type `int?`: - -[!code-csharp[csProgGuideLINQ#83](~/samples/snippets/csharp/concepts/linq/how-to-handle-null-values-in-query-expressions_2.cs)] - -In each of the examples, the `equals` query keyword is used. You can also use [pattern matching](../language-reference/operators/patterns.md), which includes patterns for `is null` and `is not null`. These patterns aren't recommended in LINQ queries because query providers may not interpret the new C# syntax correctly. A query provider is a library that translates C# query expressions into a native data format, such as Entity Framework Core. Query providers implement the interface to create data sources that implement the interface. - -## See also - -- -- [Language Integrated Query (LINQ)](index.md) -- [Nullable value types](../language-reference/builtin-types/nullable-value-types.md) diff --git a/docs/csharp/linq/how-to-build-dynamic-queries.md b/docs/csharp/linq/how-to-build-dynamic-queries.md new file mode 100644 index 0000000000000..d39dfb7ebce67 --- /dev/null +++ b/docs/csharp/linq/how-to-build-dynamic-queries.md @@ -0,0 +1,143 @@ +--- +title: "How to Build LINQ Queries based on run-time state" +description: Learn to query dynamically depending on run-time state, by varying either LINQ method calls or the expression trees passed into those methods. +ms.topic: how-to +ms.date: 04/22/2024 +--- +# Query based on run-time state + +In most LINQ queries, the general shape of the query is set in code. You might filter items using a `where` clause, sort the output collection using `orderby`, group items, or perform some computation. Your code might provide parameters for the filter, or the sort key, or other expressions that are part of the query. However, the overall shape of the query can't change. In this article, you learn techniques to use interface and types that implement it to modify the shape of a query at run time. + +You use these techniques to build queries at run time, where some user input or run-time state changes the query methods you want to use as part of the query. You want to edit the query by adding, removing, or modifying query clauses. + +> [!NOTE] +> Make sure you add `using System.Linq.Expressions;` and `using static System.Linq.Expressions.Expression;` at the top of your *.cs* file. + +Consider code that defines an or an against a data source: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Initialize"::: + +Every time you run the preceding code, the same exact query is executed. Let's learn how to modify the query extend it or modify it. Fundamentally, an has two components: + +- —a language-agnostic and datasource-agnostic representation of the current query's components, in the form of an expression tree. +- —an instance of a LINQ provider, which knows how to materialize the current query into a value or set of values. + +In the context of dynamic querying, the provider usually remains the same; the expression tree of the query differs from query to query. + +Expression trees are immutable; if you want a different expression tree—and thus a different query—you need to translate the existing expression tree to a new one. The following sections describe specific techniques for querying differently in response to run-time state: + +- Use run-time state from within the expression tree +- Call more LINQ methods +- Vary the expression tree passed into the LINQ methods +- Construct an expression tree using the factory methods at +- Add method call nodes to an 's expression tree +- Construct strings, and use the [Dynamic LINQ library](https://dynamic-linq.net/) + +Each of techniques enables more capabilities, but at a cost of increased complexity. + +## Use run-time state from within the expression tree + +The simplest way to query dynamically is to reference the run-time state directly in the query via a closed-over variable, such as `length` in the following code example: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Runtime_state_from_within_expression_tree"::: + +The internal expression tree—and thus the query—isn't modified; the query returns different values only because the value of `length` changed. + +## Call more LINQ methods + +Generally, the [built-in LINQ methods](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs) at perform two steps: + +- Wrap the current expression tree in a representing the method call. +- Pass the wrapped expression tree back to the provider, either to return a value via the provider's method; or to return a translated query object via the method. + +You can replace the original query with the result of an -returning method, to get a new query. You can use run-time state, as in the following example: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Added_method_calls"::: + +## Vary the expression tree passed into the LINQ methods + +You can pass in different expressions to the LINQ methods, depending on run-time state: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Varying_expressions"::: + +You might also want to compose the various subexpressions using another library such as [LinqKit](http://www.albahari.com/nutshell/linqkit.aspx)'s [PredicateBuilder](http://www.albahari.com/nutshell/predicatebuilder.aspx): + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Compose_expressions"::: + +## Construct expression trees and queries using factory methods + +In all the examples up to this point, you know the element type at compile time—`string`—and thus the type of the query—`IQueryable`. You might add components to a query of any element type, or to add different components, depending on the element type. You can create expression trees from the ground up, using the factory methods at , and thus tailor the expression at run time to a specific element type. + +## Constructing an Expression\ + +When you construct an expression to pass into one of the LINQ methods, you're actually constructing an instance of , where `TDelegate` is some delegate type such as `Func`, `Action`, or a custom delegate type. + + inherits from , which represents a complete lambda expression like the following example: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Compiler_generated_expression_tree"::: + +A has two components: + +1. A parameter list—`(string x)`—represented by the property. +1. A body—`x.StartsWith("a")`—represented by the property. + +The basic steps in constructing an are as follows: + +1. Define objects for each of the parameters (if any) in the lambda expression, using the factory method. + :::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Factory_method_expression_tree_parameter"::: +1. Construct the body of your , using the defined, and the factory methods at . For instance, an expression representing `x.StartsWith("a")` could be constructed like this: + :::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Factory_method_expression_tree_body"::: +1. Wrap the parameters and body in a compile-time-typed [Expression\](xref:System.Linq.Expressions.Expression%601), using the appropriate factory method overload: + :::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Factory_method_expression_tree_lambda"::: + +The following sections describe a scenario in which you might want to construct an to pass into a LINQ method. It provides a complete example of how to do so using the factory methods. + +## Construct a full query at run time + +You want to write queries that work with multiple entity types: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Entities"::: + +For any of these entity types, you want to filter and return only those entities that have a given text inside one of their `string` fields. For `Person`, you'd want to search the `FirstName` and `LastName` properties: + +```csharp +string term = /* ... */; +var personsQry = new List() + .AsQueryable() + .Where(x => x.FirstName.Contains(term) || x.LastName.Contains(term)); +``` + +But for `Car`, you'd want to search only the `Model` property: + +```csharp +string term = /* ... */; +var carsQry = new List() + .AsQueryable() + .Where(x => x.Model.Contains(term)); +``` + +While you could write one custom function for `IQueryable` and another for `IQueryable`, the following function adds this filtering to any existing query, irrespective of the specific element type. + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Factory_methods_expression_of_tdelegate"::: + +Because the `TextFilter` function takes and returns an (and not just an ), you can add further compile-time-typed query elements after the text filter. + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Factory_methods_expression_of_tdelegate_usage"::: + +### Add method call nodes to the IQueryable\'s expression tree + +If you have an instead of an , you can't directly call the generic LINQ methods. One alternative is to build the inner expression tree as shown in the previous example, and use reflection to invoke the appropriate LINQ method while passing in the expression tree. + +You could also duplicate the LINQ method's functionality, by wrapping the entire tree in a that represents a call to the LINQ method: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Factory_methods_lambdaexpression"::: + +In this case, you don't have a compile-time `T` generic placeholder, so you use the overload that doesn't require compile-time type information, and which produces a instead of an . + +### The Dynamic LINQ library + +Constructing expression trees using factory methods is relatively complex; it's easier to compose strings. The [Dynamic LINQ library](https://dynamic-linq.net/) exposes a set of extension methods on corresponding to the standard LINQ methods at , and which accept strings in a [special syntax](https://dynamic-linq.net/expression-language) instead of expression trees. The library generates the appropriate expression tree from the string, and can return the resultant translated . + +For instance, the previous example could be rewritten as follows: + +:::code language="csharp" source="./snippets/HowToBuildDynamicQueries/Program.cs" id="Dynamic_linq"::: diff --git a/docs/csharp/linq/how-to-extend-linq.md b/docs/csharp/linq/how-to-extend-linq.md new file mode 100644 index 0000000000000..d4a550ab7af86 --- /dev/null +++ b/docs/csharp/linq/how-to-extend-linq.md @@ -0,0 +1,114 @@ +--- +title: "How to: Write your own extensions to LINQ" +description: Learn techniques to extend the standard LINQ methods. Query based on runtime state, modify query objects, and extend LINQ capabilities. +ms.topic: how-to +ms.date: 04/22/2024 +--- +# How to extend LINQ + +All LINQ based methods follow one of two similar patterns. They take an enumerable sequence. They return either a different sequence, or a single value. The consistency of the shape enables you to extend LINQ by writing methods with a similar shape. In fact, the .NET libraries have gained new methods in many .NET releases since LINQ was first introduced. In this article, you see examples of extending LINQ by writing your own methods that follow the same pattern. + +## Add custom methods for LINQ queries + +You extend the set of methods that you use for LINQ queries by adding extension methods to the interface. For example, in addition to the standard average or maximum operations, you create a custom aggregate method to compute a single value from a sequence of values. You also create a method that works as a custom filter or a specific data transform for a sequence of values and returns a new sequence. Examples of such methods are , , and . + +When you extend the interface, you can apply your custom methods to any enumerable collection. For more information, see [Extension Methods](../programming-guide/classes-and-structs/extension-methods.md). + +An *aggregate* method computes a single value from a set of values. LINQ provides several aggregate methods, including , , and . You can create your own aggregate method by adding an extension method to the interface. + +The following code example shows how to create an extension method called `Median` to compute a median for a sequence of numbers of type `double`. + +:::code language="csharp" source="./snippets/HowToExtend/LinqExtensions.cs" ID="LinqExtensionClass"::: + +You call this extension method for any enumerable collection in the same way you call other aggregate methods from the interface. + +The following code example shows how to use the `Median` method for an array of type `double`. + +:::code language="csharp" source="./snippets/HowToExtend/Program.cs" ID="MedianUsage"::: + +You can *overload your aggregate method* so that it accepts sequences of various types. The standard approach is to create an overload for each type. Another approach is to create an overload that takes a generic type and convert it to a specific type by using a delegate. You can also combine both approaches. + +You can create a specific overload for each type that you want to support. The following code example shows an overload of the `Median` method for the `int` type. + +:::code language="csharp" source="./snippets/HowToExtend/LinqExtensions.cs" ID="IntOverload"::: + +You can now call the `Median` overloads for both `integer` and `double` types, as shown in the following code: + +:::code language="csharp" source="./snippets/HowToExtend/Program.cs" ID="OverloadUsage"::: + +You can also create an overload that accepts a *generic sequence* of objects. This overload takes a delegate as a parameter and uses it to convert a sequence of objects of a generic type to a specific type. + +The following code shows an overload of the `Median` method that takes the delegate as a parameter. This delegate takes an object of generic type T and returns an object of type `double`. + +:::code language="csharp" source="./snippets/HowToExtend/LinqExtensions.cs" ID="GenericOverload"::: + +You can now call the `Median` method for a sequence of objects of any type. If the type doesn't have its own method overload, you have to pass a delegate parameter. In C#, you can use a lambda expression for this purpose. Also, in Visual Basic only, if you use the `Aggregate` or `Group By` clause instead of the method call, you can pass any value or expression that is in the scope this clause. + +The following example code shows how to call the `Median` method for an array of integers and an array of strings. For strings, the median for the lengths of strings in the array is calculated. The example shows how to pass the delegate parameter to the `Median` method for each case. + +:::code language="csharp" source="./snippets/HowToExtend/Program.cs" ID="GenericUsage"::: + +You can extend the interface with a custom query method that returns a *sequence of values*. In this case, the method must return a collection of type . Such methods can be used to apply filters or data transforms to a sequence of values. + +The following example shows how to create an extension method named `AlternateElements` that returns every other element in a collection, starting from the first element. + +:::code language="csharp" source="./snippets/HowToExtend/LinqExtensions.cs" ID="SequenceElement"::: + +You can call this extension method for any enumerable collection just as you would call other methods from the interface, as shown in the following code: + +:::code language="csharp" source="./snippets/HowToExtend/Program.cs" ID="SequenceUsage"::: + +## Group results by contiguous keys + +The following example shows how to group elements into chunks that represent subsequences of contiguous keys. For example, assume that you're given the following sequence of key-value pairs: + +|Key | Value | +|----|--------| +| A | We | +| A | think | +| A | that | +| B | Linq | +| C | is | +| A | really | +| B | cool | +| B | ! | + +The following groups are created in this order: + +1. We, think, that +1. Linq +1. is +1. really +1. cool, ! + +The solution is implemented as a thread-safe extension method that returns its results in a streaming manner. It produces its groups as it moves through the source sequence. Unlike the `group` or `orderby` operators, it can begin returning groups to the caller before reading the entire sequence. The following example shows both the extension method and the client code that uses it: + +:::code language="csharp" source="./snippets/HowToExtend/GroupByContiguousKeys.cs" id="group_by_contiguous_keys_chunkextensions"::: + +:::code language="csharp" source="./snippets/HowToExtend/GroupByContiguousKeys.cs" id="group_by_contiguous_keys_client_code"::: + +### `ChunkExtensions` class + +In the presented code of the `ChunkExtensions` class implementation, the `while(true)` loop in the `ChunkBy` method iterates through source sequence and creates a copy of each Chunk. On each pass, the iterator advances to the first element of the next "Chunk", represented by a [`Chunk`](#chunk-class) object, in the source sequence. This loop corresponds to the outer foreach loop that executes the query. In that loop, the code does the following actions: + +1. Get the key for the current Chunk and assign it to `key` variable. The source iterator consumes the source sequence until it finds an element with a key that doesn't match. +1. Make a new Chunk (group) object, and store it in `current` variable. It has one GroupItem, a copy of the current source element. +1. Return that Chunk. A Chunk is an `IGrouping`, which is the return value of the [`ChunkBy`](#chunk-class) method. The Chunk only has the first element in its source sequence. The remaining elements are returned only when the client code foreach's over this chunk. See `Chunk.GetEnumerator` for more info. +1. Check to see if: + - The chunk has a copy of all its source elements, or + - The iterator reached the end of the source sequence. +1. When the caller has enumerated all the chunk items, the `Chunk.GetEnumerator` method has copied all chunk items. If the `Chunk.GetEnumerator` loop didn't enumerate all elements in the chunk, do it now to avoid corrupting the iterator for clients that might be calling it on a separate thread. + +### `Chunk` class + +The `Chunk` class is a contiguous group of one or more source elements that have the same key. A Chunk has a key and a list of ChunkItem objects, which are copies of the elements in the source sequence: + +:::code language="csharp" source="./snippets/HowToExtend/GroupByContiguousKeys.cs" id="group_by_contiguous_keys_chunk_class"::: + +Each `ChunkItem` (represented by `ChunkItem` class) has a reference to the next `ChunkItem` in the list. The list consists of its `head` - which stores the contents of the first source element that belongs with this chunk, and its `tail` - which is an end of the list. The tail is repositioned each time a new `ChunkItem` is added. The tail of the linked list is set to `null` in the `CopyNextChunkElement` method if the key of the next element doesn't match the current chunk's key, or there are no more elements in the source. + +The `CopyNextChunkElement` method of the `Chunk` class adds one `ChunkItem` to the current group of items. It tries to advance the iterator on the source sequence. If the `MoveNext()` method returns `false` the iteration is at the end, and `isLastSourceElement` is set to `true`. + +The `CopyAllChunkElements` method is called after the end of the last chunk was reached. It checks whether there are more elements in the source sequence. If there are, it returns `true` if the enumerator for this chunk was exhausted. In this method, when the private `DoneCopyingChunk` field is checked for `true`, if isLastSourceElement is `false`, it signals to the outer iterator to continue iterating. + +The inner foreach loop invokes the `GetEnumerator` method of the `Chunk` class. This method stays one element ahead of the client requests. It adds the next element of the chunk only after the client requests the previous last element in the list. diff --git a/docs/csharp/linq/how-to-query-collections.md b/docs/csharp/linq/how-to-query-collections.md new file mode 100644 index 0000000000000..3d661a92524e3 --- /dev/null +++ b/docs/csharp/linq/how-to-query-collections.md @@ -0,0 +1,71 @@ +--- +title: "How to: use LINQ to query or modify collections" +description: This series of examples shows you Language Integrated Query (LINQ) techniques to use with collections and arrays. +ms.topic: how-to +ms.date: 04/22/2024 +--- +# LINQ and collections + +Most collections model a *sequence* of elements. You can use LINQ to query any collection type. Other LINQ methods find elements in a collection, compute values from the elements in a collection, or modify the collection or its elements. These examples help you learn about LINQ methods and how you can use them with your collections, or other data sources. + +## How to find the set difference between two lists + +This example shows how to use LINQ to compare two lists of strings and output those lines that are in first collection, but not in the second. The first collection of names is stored in the file *names1.txt*: + +:::code language="txt" source="./snippets/HowToCollections/names1.txt" ::: + +The second collection of names is stored in the file *names2.txt*. Some names appear in both sequences. + +:::code language="txt" source="./snippets/HowToCollections/names2.txt" ::: + +The following code shows how you can use the method to find elements in the first list that aren't in the second list: + +:::code language="csharp" source="./snippets/HowToCollections/Program.cs" id="SnippetSetDifferences"::: + +Some types of query operations, such as , , , and , can only be expressed in method-based syntax. + +## How to combine and compare string collections + +This example shows how to merge files that contain lines of text and then sort the results. Specifically, it shows how to perform a concatenation, a union, and an intersection on the two sets of text lines. It uses the same two text files shows in the preceding example. The code shows examples of the , , and . + +:::code language="csharp" source="./snippets/HowToCollections/Program.cs" id="CombineCompareStringCollections"::: + +## How to populate object collections from multiple sources + +This example shows how to merge data from different sources into a sequence of new types. + +> [!NOTE] +> Don't try to join in-memory data or data in the file system with data that is still in a database. Such cross-domain joins can yield undefined results because of different ways in which join operations might be defined for database queries and other types of sources. Additionally, there is a risk that such an operation could cause an out-of-memory exception if the amount of data in the database is large enough. To join data from a database to in-memory data, first call `ToList` or `ToArray` on the database query, and then perform the join on the returned collection. + +This example uses two files. The first, *names.csv*, contains student names and student IDs. + +:::code language="txt" source="./snippets/HowToCollections/names.csv" ::: + +The second, *scores.csv*, contains student IDs in the first column, followed by exam scores. + +:::code language="txt" source="./snippets/HowToCollections/scores.csv" ::: + +The following example shows how to use a named record `Student` to store merged data from two in-memory collections of strings that simulate spreadsheet data in .csv format. The ID is used as the key to map students to their scores. + +:::code language="csharp" source="./snippets/HowToCollections/Program.cs" id="PopulateCollection"::: + +In the [select](../language-reference/keywords/select-clause.md) clause, each new `Student` object is initialized from the data in the two sources. + +If you don't have to store the results of a query, tuples or anonymous types can be more convenient than named types. The following example executes the same task as the previous example, but uses tuples instead of named types: + +:::code language="csharp" source="./snippets/HowToCollections/Program.cs" id="PopulateCollection2"::: + +## How to query an ArrayList with LINQ + +When using LINQ to query nongeneric collections such as , you must explicitly declare the type of the range variable to reflect the specific type of the objects in the collection. If you have an of `Student` objects, your [from clause](../language-reference/keywords/from-clause.md) should look like this: + +```csharp +var query = from Student s in arrList +//... +``` + +By specifying the type of the range variable, you're casting each item in the to a `Student`. + +The use of an explicitly typed range variable in a query expression is equivalent to calling the method. throws an exception if the specified cast can't be performed. and are the two Standard Query Operator methods that operate on nongeneric types. For more information, see [Type Relationships in LINQ Query Operations](get-started/type-relationships-in-linq-query-operations.md). The following example shows a query over an . + +:::code language="csharp" source="./snippets/HowToCollections/Program.cs" id="QueryArrayList"::: diff --git a/docs/csharp/linq/how-to-query-files-and-directories.md b/docs/csharp/linq/how-to-query-files-and-directories.md new file mode 100644 index 0000000000000..3b27e97cfb320 --- /dev/null +++ b/docs/csharp/linq/how-to-query-files-and-directories.md @@ -0,0 +1,133 @@ +--- +title: "Use LINQ to query files and directories" +description: Use Language Integrated Query (LINQ) for file system operations that don't to change the contents of the files or folders. +ms.date: 04/22/2024 +--- +# How to: Use LINQ to query files and directories + +Many file system operations are essentially queries and are therefore well suited to the LINQ approach. These queries are nondestructive. They don't change the contents of the original files or folders. Queries shouldn't cause any side-effects. In general, any code (including queries that perform create / update / delete operations) that modifies source data should be kept separate from the code that just queries the data. + +There's some complexity involved in creating a data source that accurately represents the contents of the file system and handles exceptions gracefully. The examples in this section create a snapshot collection of objects that represents all the files under a specified root folder and all its subfolders. The actual state of each might change in the time between when you begin and end executing a query. For example, you can create a list of objects to use as a data source. If you try to access the `Length` property in a query, the object tries to access the file system to update the value of `Length`. If the file no longer exists, you get a in your query, even though you aren't querying the file system directly. + +## How to query for files with a specified attribute or name + +This example shows how to find all files that have a specified file name extension (for example ".txt") in a specified directory tree. It also shows how to return either the newest or oldest file in the tree based on the creation time. You might need to modify the first line of many of the samples whether you're running this code on either Windows, Mac, or a Linux system. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="FindFilesByExtension"::: + +## How to group files by extension + +This example shows how LINQ can be used to perform advanced grouping and sorting operations on lists of files or folders. It also shows how to page output in the console window by using the and methods. + +The following query shows how to group the contents of a specified directory tree by the file name extension. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="GroupFilesByExtension"::: + +The output from this program can be long, depending on the details of the local file system and what the `startFolder` is set to. To enable viewing of all results, this example shows how to page through results. A nested `foreach` loop is required because each group is enumerated separately. + +## How to query for the total number of bytes in a set of folders + +This example shows how to retrieve the total number of bytes used by all the files in a specified folder and all its subfolders. The method adds the values of all the items selected in the `select` clause. You can modify this query to retrieve the biggest or smallest file in the specified directory tree by calling the or method instead of . + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="QueryByFileSize"::: + +This example extends the previous example to do the following: + +- How to retrieve the size in bytes of the largest file. +- How to retrieve the size in bytes of the smallest file. +- How to retrieve the object largest or smallest file from one or more folders under a specified root folder. +- How to retrieve a sequence such as the 10 largest files. +- How to order files into groups based on their file size in bytes, ignoring files that are less than a specified size. + +The following example contains five separate queries that show how to query and group files, depending on their file size in bytes. You can modify these examples to base the query on some other property of the object. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="MoreQueriesOnFileSizes"::: + +To return one or more complete objects, the query first must examine each one in the data source, and then sort them by the value of their Length property. Then it can return the single one or the sequence with the greatest lengths. Use to return the first element in a list. Use to return the first n number of elements. Specify a descending sort order to put the smallest elements at the start of the list. + +## How to query for duplicate files in a directory tree + +Sometimes files that have the same name can be located in more than one folder. This example shows how to query for such duplicate file names under a specified root folder. The second example shows how to query for files whose size and LastWrite times also match. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/DuplicateFileQuery.cs" id="QueryDuplicateNames"::: + +The first query uses a key to determine a match. It finds files that have the same name but whose contents might be different. The second query uses a compound key to match against three properties of the object. This query is much more likely to find files that have the same name and similar or identical content. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/DuplicateFileQuery.cs" id="QueryDuplicateFileInfo"::: + +## How to query the contents of text files in a folder + +This example shows how to query over all the files in a specified directory tree, open each file, and inspect its contents. This type of technique could be used to create indexes or reverse indexes of the contents of a directory tree. A simple string search is performed in this example. However, more complex types of pattern matching can be performed with a regular expression. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="QueryTextContent"::: + +## How to compare the contents of two folders + +This example demonstrates three ways to compare two file listings: + +- By querying for a Boolean value that specifies whether the two file lists are identical. +- By querying for the intersection to retrieve the files that are in both folders. +- By querying for the set difference to retrieve the files that are in one folder but not the other. + +The techniques shown here can be adapted to compare sequences of objects of any type. + +The `FileComparer` class shown here demonstrates how to use a custom comparer class together with the Standard Query Operators. The class isn't intended for use in real-world scenarios. It just uses the name and length in bytes of each file to determine whether the contents of each folder are identical or not. In a real-world scenario, you should modify this comparer to perform a more rigorous equality check. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/CompareDirectoryContents.cs" id="CompareDirectoryContents"::: + +## How to reorder the fields of a delimited file + +A comma-separated value (CSV) file is a text file that is often used to store spreadsheet data or other tabular data represented by rows and columns. By using the method to separate the fields, it's easy to query and manipulate CSV files using LINQ. In fact, the same technique can be used to reorder the parts of any structured line of text; it isn't limited to CSV files. + +In the following example, assume that the three columns represent students' "family name," "first name", and "ID." The fields are in alphabetical order based on the students' family names. The query produces a new sequence in which the ID column appears first, followed by a second column that combines the student's first name and family name. The lines are reordered according to the ID field. The results are saved into a new file and the original data isn't modified. The following text shows the contents of the *spreadsheet1.csv* file used in the following example: + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/spreadsheet1.csv"::: + +The following code reads the source file and rearranges each column in the CSV file to rearrange the order of the columns: + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="UpdateFileContent"::: + +## How to split a file into many files by using groups + +This example shows one way to merge the contents of two files and then create a set of new files that organize the data in a new way. The query uses the contents of two files. The following text shows the contents of the first file, *names1.txt*: + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/names1.txt"::: + +The second file, *names2.txt*, contains a different set of names, some of which are in common with the first set: + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/names2.txt"::: + +The following code queries both files, takes the union of both files, then writes a new file for each group, defined by the first letter of the family name: + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="SplitFileIntoGroups"::: + +## How to join content from dissimilar files + +This example shows how to join data from two comma-delimited files that share a common value that is used as a matching key. This technique can be useful if you have to combine data from two spreadsheets, or from a spreadsheet and from a file that has another format, into a new file. You can modify the example to work with any kind of structured text. + +The following text shows the contents of *scores.csv*. The file represents spreadsheet data. Column 1 is the student's ID, and columns 2 through 5 are test scores. + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/scores.csv"::: + +The following text shows the contents of *names.csv*. The file represents a spreadsheet that contains the student's family name, first name, and student ID. + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/names.csv"::: + +Join content from dissimilar files that contain related information. File *names.csv* contains the student name plus an ID number. File *scores.csv* contains the ID and a set of four test scores. The following query joins the scores to the student names by using ID as a matching key. The code is shown in the following example: + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/Program.cs" id="JoinDissimilarFiles"::: + +## How to compute column values in a CSV text file + +This example shows how to perform aggregate computations such as Sum, Average, Min, and Max on the columns of a .csv file. The example principles that are shown here can be applied to other types of structured text. + +The following text shows the contents of *scores.csv*. Assume that the first column represents a student ID, and subsequent columns represent scores from four exams. + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/scores.csv"::: + +The following text shows how to use the method to convert each line of text into an array. Each array element represents a column. Finally, the text in each column is converted to its numeric representation. + +:::code language="csharp" source="./snippets/HowToFilesAndDirectories/SumColumns.cs" id="SumColumns"::: + +If your file is a tab-separated file, just update the argument in the `Split` method to `\t`. + \ No newline at end of file diff --git a/docs/csharp/linq/how-to-query-strings.md b/docs/csharp/linq/how-to-query-strings.md new file mode 100644 index 0000000000000..41bf25817266d --- /dev/null +++ b/docs/csharp/linq/how-to-query-strings.md @@ -0,0 +1,55 @@ +--- +title: "Use LINQ to query strings" +description: You can query a string as a sequence of characters in LINQ. This article contains several examples you can use or modify to suit your needs. +ms.topic: how-to +ms.date: 04/22/2024 +--- +# How to: Use LINQ to query strings + +Strings are stored as a sequence of characters. As a sequence of characters, they can be queried using LINQ. In this article, there are several example queries that query strings for different characters or words, filter strings, or mix queries with regular expressions. + +## How to query for characters in a string + +The following example queries a string to determine the number of numeric digits it contains. + +:::code language="csharp" source="./snippets/HowToStrings/Program.cs" id="CharsInAString"::: + +The preceding query shows how you can treat a string as a sequence of characters. + +## How to count occurrences of a word in a string + +The following example shows how to use a LINQ query to count the occurrences of a specified word in a string. To perform the count, first the method is called to create an array of words. There's a performance cost to the method. If the only operation on the string is to count the words, consider using the or methods instead. + +:::code language="csharp" source="./snippets/HowToStrings/Program.cs" id="CountWordsInAString"::: + +The preceding query shows how you can view strings as a sequence of words, after splitting a string into a sequence of words. + +## How to sort or filter text data by any word or field + +The following example shows how to sort lines of structured text, such as comma-separated values, by any field in the line. The field can be dynamically specified at run time. Assume that the fields in *scores.csv* represent a student's ID number, followed by a series of four test scores: + +:::code language="txt" source="./snippets/HowToFilesAndDirectories/scores.csv"::: + +The following query sorts the lines based on the score of the first exam, stored in the second column: + +:::code language="csharp" source="./snippets/HowToStrings/Program.cs" id="SortStrings"::: + +The preceding query shows how you can manipulate strings by splitting them into fields, and querying the individual fields. + +## How to query for sentences that specific words + +The following example shows how to find sentences in a text file that contain matches for each of a specified set of words. Although the array of search terms is hard-coded, it could also be populated dynamically at run time. The query returns the sentences that contain the words "Historically," "data," and "integrated." + +:::code language="csharp" source="./snippets/HowToStrings/Program.cs" id="FindSentences"::: + +The query first splits the text into sentences, and then splits each sentence into an array of strings that hold each word. For each of these arrays, the method removes all duplicate words, and then the query performs an operation on the word array and the `wordsToMatch` array. If the count of the intersection is the same as the count of the `wordsToMatch` array, all words were found in the words and the original sentence is returned. + +The call to uses punctuation marks as separators in order to remove them from the string. If you didn't do remove punctuation, for example you could have a string "Historically," that wouldn't match "Historically" in the `wordsToMatch` array. You might have to use extra separators, depending on the types of punctuation found in the source text. + +## How to combine LINQ queries with regular expressions + +The following example shows how to use the class to create a regular expression for more complex matching in text strings. The LINQ query makes it easy to filter on exactly the files that you want to search with the regular expression, and to shape the results. + +:::code language="csharp" source="./snippets/HowToStrings/Program.cs" id="QueryWithRegEx"::: + +You can also query the object returned by a `RegEx` search. Only the value of each match is produced in the results. However, it's also possible to use LINQ to perform all kinds of filtering, sorting, and grouping on that collection. Because is a nongeneric collection, you have to explicitly state the type of the range variable in the query. diff --git a/docs/csharp/linq/query-a-collection-of-objects.md b/docs/csharp/linq/query-a-collection-of-objects.md deleted file mode 100644 index b08c6782eb363..0000000000000 --- a/docs/csharp/linq/query-a-collection-of-objects.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Query a collection of objects (LINQ in C#) -description: Learn how query collections using LINQ in C#. -ms.date: 07/16/2023 ---- -# Query a collection of objects - -The term "LINQ to Objects" refers to the use of LINQ queries with any or collection directly, without the use of an intermediate LINQ provider or API such as [LINQ to SQL](../../framework/data/adonet/sql/linq/index.md) or [LINQ to XML](../../standard/linq/linq-xml-overview.md). You can use LINQ to query any enumerable collections such as , , or . The collection may be user-defined or may be returned by a .NET API. In the LINQ approach, you write declarative code that describes what you want to retrieve. - -In addition, LINQ queries offer three main advantages over traditional `foreach` loops: - -- They are more concise and readable, especially when filtering multiple conditions. -- They provide powerful filtering, ordering, and grouping capabilities with a minimum of application code. -- They can be ported to other data sources with little or no modification. - -In general, the more complex the operation you want to perform on the data, the more benefit you'll realize by using LINQ instead of traditional iteration techniques. - -This example shows how to perform a simple query over a list of `Student` objects. Each `Student` object contains some basic information about the student, and a list that represents the student's scores on four examinations. - -> [!NOTE] -> Many other examples in this section use the same `Student` class and `students` collection. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/DataClasses.cs" id="query_a_collection_of_objects_1"::: - -## Example - -The following query returns the students who received a score of 90 or greater on their first exam. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/QueryCollectionOfObjects.cs" id="query_a_collection_of_objects_2"::: - -This query is intentionally simple to enable you to experiment. For example, you can try more conditions in the `where` clause, or use an `orderby` clause to sort the results. - -## Classification of standard query operators by manner of execution - -The LINQ to Objects implementations of the standard query operator methods execute in one of two main ways: immediate or deferred. The query operators that use deferred execution can be additionally divided into two categories: streaming and non-streaming. If you know how the different query operators execute, it may help you understand the results that you get from a given query. This is especially true if the data source is changing or if you are building a query on top of another query. This topic classifies the standard query operators according to their manner of execution. - -### Immediate - - Immediate execution means that the data source is read and the operation is performed once. All the standard query operators that return a scalar result execute immediately. You can force a query to execute immediately using the or methods. Immediate execution provides reuse of query results, not query declaration. The results are retrieved once, then stored for future use. - -### Deferred - - Deferred execution means that the operation is not performed at the point in the code where the query is declared. The operation is performed only when the query variable is enumerated, for example by using a `foreach` statement. This means that the results of executing the query depend on the contents of the data source when the query is executed rather than when the query is defined. If the query variable is enumerated multiple times, the results might differ every time. Almost all the standard query operators whose return type is or execute in a deferred manner. Deferred execution provides the facility of query reuse since the query fetches the updated data from the data source each time query results are iterated. - - Query operators that use deferred execution can be additionally classified as streaming or non-streaming. - -#### Streaming - - Streaming operators do not have to read all the source data before they yield elements. At the time of execution, a streaming operator performs its operation on each source element as it is read and yields the element if appropriate. A streaming operator continues to read source elements until a result element can be produced. This means that more than one source element might be read to produce one result element. - -#### Non-streaming - - Non-streaming operators must read all the source data before they can yield a result element. Operations such as sorting or grouping fall into this category. At the time of execution, non-streaming query operators read all the source data, put it into a data structure, perform the operation, and yield the resulting elements. - -## Classification table - - The following table classifies each standard query operator method according to its method of execution. - -> [!NOTE] -> If an operator is marked in two columns, two input sequences are involved in the operation, and each sequence is evaluated differently. In these cases, it is always the first sequence in the parameter list that is evaluated in a deferred, streaming manner. - -|Standard query operator | Return type | Immediate execution | Deferred streaming execution | Deferred Non-streaming execution | -|-----------------------------|-----------------|-------------------------|----------------------------------|---------------------------------------| -||`TSource`|X||| -|||X||| -|||X||| -||||X|| -||Single numeric value|X||| -||||X|| -||||X|| -|||X||| -|||X||| -||||X|| -||||X|| -||`TSource`|X||| -||`TSource?`|X||| -|||X||| -||||X|X| -||`TSource`|X||| -||`TSource?`|X||| -|||||X| -||||X|X| -||||X|X| -||||X|X| -||`TSource`|X||| -||`TSource?`|X||| -|||X||| -||Single numeric value, `TSource`, or `TResult?`|X||| -||Single numeric value, `TSource`, or `TResult?`|X||| -||||X|| -|||||X| -|||||X| -||||X|| -||||X|| -|||||X| -||||X|| -||||X|| -|||X||| -||`TSource`|X||| -||`TSource?`|X||| -||||X|| -||||X|| -||Single numeric value|X||| -||||X|| -||||X|| -|||||X| -|||||X| -||`TSource[]` array|X||| -|||X||| -|||X||| -|||X||| -||||X|| -||||X|| - -## See also - -- [Language Integrated Query (LINQ)](index.md) -- [String interpolation](../language-reference/tokens/interpolated.md) diff --git a/docs/csharp/linq/return-a-query-from-a-method.md b/docs/csharp/linq/return-a-query-from-a-method.md deleted file mode 100644 index 629272b9fd077..0000000000000 --- a/docs/csharp/linq/return-a-query-from-a-method.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Return a query from a method -description: How to return a query. -ms.date: 11/30/2016 -ms.assetid: db220f79-c35b-41f2-886c-cd068672d42d ---- -# How to return a query from a method - -This example shows how to return a query from a method as the return value and as an `out` parameter. - - Query objects are composable, meaning that you can return a query from a method. Objects that represent queries do not store the resulting collection, but rather the steps to produce the results when needed. The advantage of returning query objects from methods is that they can be further composed or modified. Therefore any return value or `out` parameter of a method that returns a query must also have that type. If a method materializes a query into a concrete or type, it is considered to be returning the query results instead of the query itself. A query variable that is returned from a method can still be composed or modified. - -## Example - -In the following example, the first method `QueryMethod1` returns a query as a return value, and the second method `QueryMethod2` returns a query as an `out` parameter (`returnQ` in the example). Note that in both cases it is a query that is returned, not query results. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs" id="return_query_from_method_1"::: - -Query `myQuery1` is executed in the following foreach loop. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs" id="return_query_from_method_2"::: - -Rest the mouse pointer over `myQuery1` to see its type. - -You also can execute the query returned from `QueryMethod1` directly, without using `myQuery1`. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs" id="return_query_from_method_3"::: - -Rest the mouse pointer over the call to `QueryMethod1` to see its return type. - -`QueryMethod2` returns a query as the value of its out parameter: -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs" id="return_query_from_method_4"::: - -You can modify a query by using query composition. In this case, the previous query object is used to create a new query object. This new object will return different results than the original query object. - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/ReturnQueryFromMethod.cs" id="return_query_from_method_5"::: - -## See also - -- [Language Integrated Query (LINQ)](index.md) diff --git a/samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.csproj b/docs/csharp/linq/snippets/HowToBuildDynamicQueries/HowToBuildDynamicQueries.csproj similarity index 79% rename from samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.csproj rename to docs/csharp/linq/snippets/HowToBuildDynamicQueries/HowToBuildDynamicQueries.csproj index 2b09b4f9fe4da..3a5ec90c6308a 100644 --- a/samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.csproj +++ b/docs/csharp/linq/snippets/HowToBuildDynamicQueries/HowToBuildDynamicQueries.csproj @@ -1,17 +1,16 @@ - + Exe net8.0 - dynamic_linq_expression_trees - enable enable + enable - + diff --git a/samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs b/docs/csharp/linq/snippets/HowToBuildDynamicQueries/Program.cs similarity index 84% rename from samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs rename to docs/csharp/linq/snippets/HowToBuildDynamicQueries/Program.cs index a15fbcfab4f0d..57a8c1f9c6e9e 100644 --- a/samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs +++ b/docs/csharp/linq/snippets/HowToBuildDynamicQueries/Program.cs @@ -1,12 +1,8 @@ using LinqKit; -using System; -using System.Collections.Generic; -using System.Linq; using System.Linq.Expressions; using static System.Linq.Expressions.Expression; using System.Reflection; using System.Linq.Dynamic.Core; -using ExpressionTreeToString; // string[] companyNames = [ @@ -18,12 +14,28 @@ "Wingtip Toys", "Lucerne Publishing", "Fourth Coffee" ]; -// We're using an in-memory array as the data source, but the IQueryable could have come +// Use an in-memory array as the data source, but the IQueryable could have come // from anywhere -- an ORM backed by a database, a web request, or any other LINQ provider. IQueryable companyNamesSource = companyNames.AsQueryable(); var fixedQry = companyNames.OrderBy(x => x); // +Console.WriteLine("Runtime state from expression tree:"); +RuntimeStateFromWithinExpressionTree(); +AddMethodCalls(); +VaryExpressions(); +ComposeExpressions(); +FactoryMethodModifyExpressionTree(); +FactoryMethodExpressionOfDelegate(); +BuildMoreExpressions(); +DynamicLinq(); + +// +Expression> expr = x => x.StartsWith("a"); +// + + +void RuntimeStateFromWithinExpressionTree() { // var length = 1; @@ -40,12 +52,13 @@ // } +void AddMethodCalls() { bool sortByLength = true; // // bool sortByLength = /* ... */; - + var qry = companyNamesSource; if (sortByLength) { @@ -54,6 +67,7 @@ // } +void VaryExpressions() { string? startsWith = ""; string? endsWith = ""; @@ -74,13 +88,14 @@ // } +void ComposeExpressions() { string? startsWith = ""; string? endsWith = ""; // // This is functionally equivalent to the previous example. - + // using LinqKit; // string? startsWith = /* ... */; // string? endsWith = /* ... */; @@ -104,21 +119,16 @@ // } -{ - // - Expression> expr = x => x.StartsWith("a"); - // -} - +void FactoryMethodModifyExpressionTree() { // - ParameterExpression x = Expression.Parameter(typeof(string), "x"); + ParameterExpression x = Parameter(typeof(string), "x"); // // Expression body = Call( x, - typeof(string).GetMethod("StartsWith", new[] { typeof(string) })!, + typeof(string).GetMethod("StartsWith", [typeof(string)])!, Constant("a") ); // @@ -128,7 +138,7 @@ // } - +void FactoryMethodExpressionOfDelegate() { // // using static System.Linq.Expressions.Expression; @@ -141,14 +151,14 @@ IQueryable TextFilter(IQueryable source, string term) Type elementType = typeof(T); // Get all the string properties on this specific type. - PropertyInfo[] stringProperties = - elementType.GetProperties() - .Where(x => x.PropertyType == typeof(string)) - .ToArray(); + PropertyInfo[] stringProperties = elementType + .GetProperties() + .Where(x => x.PropertyType == typeof(string)) + .ToArray(); if (!stringProperties.Any()) { return source; } // Get the right overload of String.Contains - MethodInfo containsMethod = typeof(string).GetMethod("Contains", new[] { typeof(string) })!; + MethodInfo containsMethod = typeof(string).GetMethod("Contains", [typeof(string)])!; // Create a parameter for the expression tree: // the 'x' in 'x => x.PropertyName.Contains("term")' @@ -171,9 +181,7 @@ IQueryable TextFilter(IQueryable source, string term) // Combine all the resultant expression nodes using || Expression body = expressions - .Aggregate( - (prev, current) => Or(prev, current) - ); + .Aggregate((prev, current) => Or(prev, current)); // Wrap the expression body in a compile-time-typed lambda expression Expression> lambda = Lambda>(body, prm); @@ -185,22 +193,24 @@ IQueryable TextFilter(IQueryable source, string term) // var qry = TextFilter( - new List().AsQueryable(), + new List().AsQueryable(), "abcd" ) .Where(x => x.DateOfBirth < new DateTime(2001, 1, 1)); var qry1 = TextFilter( - new List().AsQueryable(), + new List().AsQueryable(), "abcd" ) .Where(x => x.Year == 2010); // } +void BuildMoreExpressions() { // This function has the logic for constructing the body of the TextFilter expression. - (Expression? body, ParameterExpression? prm) constructBody(Type elementType, string term) { + (Expression? body, ParameterExpression? prm) constructBody(Type elementType, string term) + { if (string.IsNullOrEmpty(term)) { return (null, null); } PropertyInfo[] stringProperties = @@ -220,8 +230,7 @@ IQueryable TextFilter(IQueryable source, string term) Constant(term) ) ) - .Aggregate( - (prev, current) => Or(prev, current) + .Aggregate((prev, current) => Or(prev, current) ); return (body, prm); @@ -236,12 +245,12 @@ IQueryable TextFilter_Untyped(IQueryable source, string term) // The logic for building the ParameterExpression and the LambdaExpression's body is the same as in the previous example, // but has been refactored into the constructBody function. (Expression? body, ParameterExpression? prm) = constructBody(elementType, term); - if (body is null) {return source;} + if (body is null) { return source; } Expression filteredTree = Call( typeof(Queryable), "Where", - new[] { elementType}, + [elementType], source.Expression, Lambda(body, prm!) ); @@ -251,22 +260,24 @@ IQueryable TextFilter_Untyped(IQueryable source, string term) // IQueryable qry = TextFilter_Untyped( - new List().AsQueryable(), + new List().AsQueryable(), "abcd" ); } +void DynamicLinq() { // // using System.Linq.Dynamic.Core - IQueryable TextFilter_Strings(IQueryable source, string term) { + IQueryable TextFilter_Strings(IQueryable source, string term) + { if (string.IsNullOrEmpty(term)) { return source; } var elementType = source.ElementType; // Get all the string property names on this specific type. - var stringProperties = + var stringProperties = elementType.GetProperties() .Where(x => x.PropertyType == typeof(string)) .ToArray(); diff --git a/docs/csharp/linq/snippets/HowToCollections/HowToCollections.csproj b/docs/csharp/linq/snippets/HowToCollections/HowToCollections.csproj new file mode 100644 index 0000000000000..e3a77c03f2868 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToCollections/HowToCollections.csproj @@ -0,0 +1,25 @@ + + + + Exe + net8.0 + enable + enable + + + + + PreserveNewest + + + PreserveNewest + + + PreserveNewest + + + PreserveNewest + + + + diff --git a/docs/csharp/linq/snippets/HowToCollections/Program.cs b/docs/csharp/linq/snippets/HowToCollections/Program.cs new file mode 100644 index 0000000000000..0e7562518381f --- /dev/null +++ b/docs/csharp/linq/snippets/HowToCollections/Program.cs @@ -0,0 +1,273 @@ +using System.Collections; + +Console.WriteLine("SetDifferences"); +SetDifferences(); +Console.WriteLine(); +Console.WriteLine("CombineCompareStringCollections"); +CombineCompareStringCollections(); +Console.WriteLine(); +Console.WriteLine("PopulateCollection"); +PopulateCollection(); +Console.WriteLine(); +Console.WriteLine("ArghArrayList"); +ArghArrayList(); + +static void SetDifferences() +{ + // + // Create the IEnumerable data sources. + string[] names1 = File.ReadAllLines("names1.txt"); + string[] names2 = File.ReadAllLines("names2.txt"); + + // Create the query. Note that method syntax must be used here. + var differenceQuery = names1.Except(names2); + + // Execute the query. + Console.WriteLine("The following lines are in names1.txt but not names2.txt"); + foreach (string s in differenceQuery) + Console.WriteLine(s); + /* Output: + The following lines are in names1.txt but not names2.txt + Potra, Cristina + Noriega, Fabricio + Aw, Kam Foo + Toyoshima, Tim + Guy, Wey Yuan + Garcia, Debra + */ + // +} + +static void CombineCompareStringCollections() +{ + // + //Put text files in your solution folder + string[] fileA = File.ReadAllLines("names1.txt"); + string[] fileB = File.ReadAllLines("names2.txt"); + + //Simple concatenation and sort. Duplicates are preserved. + var concatQuery = fileA.Concat(fileB).OrderBy(s => s); + + // Pass the query variable to another function for execution. + OutputQueryResults(concatQuery, "Simple concatenate and sort. Duplicates are preserved:"); + + // Concatenate and remove duplicate names based on + // default string comparer. + var uniqueNamesQuery = fileA.Union(fileB).OrderBy(s => s); + OutputQueryResults(uniqueNamesQuery, "Union removes duplicate names:"); + + // Find the names that occur in both files (based on + // default string comparer). + var commonNamesQuery = fileA.Intersect(fileB); + OutputQueryResults(commonNamesQuery, "Merge based on intersect:"); + + // Find the matching fields in each list. Merge the two + // results by using Concat, and then + // sort using the default string comparer. + string nameMatch = "Garcia"; + + var tempQuery1 = from name in fileA + let n = name.Split(',') + where n[0] == nameMatch + select name; + + var tempQuery2 = from name2 in fileB + let n2 = name2.Split(',') + where n2[0] == nameMatch + select name2; + + var nameMatchQuery = tempQuery1.Concat(tempQuery2).OrderBy(s => s); + OutputQueryResults(nameMatchQuery, $"""Concat based on partial name match "{nameMatch}":"""); + + static void OutputQueryResults(IEnumerable query, string message) + { + Console.WriteLine(Environment.NewLine + message); + foreach (string item in query) + { + Console.WriteLine(item); + } + Console.WriteLine($"{query.Count()} total names in list"); + } + /* Output: + Simple concatenate and sort. Duplicates are preserved: + Aw, Kam Foo + Bankov, Peter + Bankov, Peter + Beebe, Ann + Beebe, Ann + El Yassir, Mehdi + Garcia, Debra + Garcia, Hugo + Garcia, Hugo + Giakoumakis, Leo + Gilchrist, Beth + Guy, Wey Yuan + Holm, Michael + Holm, Michael + Liu, Jinghao + McLin, Nkenge + Myrcha, Jacek + Noriega, Fabricio + Potra, Cristina + Toyoshima, Tim + 20 total names in list + + Union removes duplicate names: + Aw, Kam Foo + Bankov, Peter + Beebe, Ann + El Yassir, Mehdi + Garcia, Debra + Garcia, Hugo + Giakoumakis, Leo + Gilchrist, Beth + Guy, Wey Yuan + Holm, Michael + Liu, Jinghao + McLin, Nkenge + Myrcha, Jacek + Noriega, Fabricio + Potra, Cristina + Toyoshima, Tim + 16 total names in list + + Merge based on intersect: + Bankov, Peter + Holm, Michael + Garcia, Hugo + Beebe, Ann + 4 total names in list + + Concat based on partial name match "Garcia": + Garcia, Debra + Garcia, Hugo + Garcia, Hugo + 3 total names in list + */ + // +} + +static void PopulateCollection() +{ + // + // Each line of names.csv consists of a last name, a first name, and an + // ID number, separated by commas. For example, Omelchenko,Svetlana,111 + string[] names = File.ReadAllLines("names.csv"); + + // Each line of scores.csv consists of an ID number and four test + // scores, separated by commas. For example, 111, 97, 92, 81, 60 + string[] scores = File.ReadAllLines("scores.csv"); + + // Merge the data sources using a named type. + // var could be used instead of an explicit type. Note the dynamic + // creation of a list of ints for the ExamScores member. The first item + // is skipped in the split string because it is the student ID, + // not an exam score. + IEnumerable queryNamesScores = from nameLine in names + let splitName = nameLine.Split(',') + from scoreLine in scores + let splitScoreLine = scoreLine.Split(',') + where Convert.ToInt32(splitName[2]) == Convert.ToInt32(splitScoreLine[0]) + select new Student + ( + FirstName: splitName[0], + LastName: splitName[1], + ID: Convert.ToInt32(splitName[2]), + ExamScores: (from scoreAsText in splitScoreLine.Skip(1) + select Convert.ToInt32(scoreAsText) + ).ToArray() + ); + + // Optional. Store the newly created student objects in memory + // for faster access in future queries. This could be useful with + // very large data files. + List students = queryNamesScores.ToList(); + + // Display each student's name and exam score average. + foreach (var student in students) + { + Console.WriteLine($"The average score of {student.FirstName} {student.LastName} is {student.ExamScores.Average()}."); + } + /* Output: + The average score of Omelchenko Svetlana is 82.5. + The average score of O'Donnell Claire is 72.25. + The average score of Mortensen Sven is 84.5. + The average score of Garcia Cesar is 88.25. + The average score of Garcia Debra is 67. + The average score of Fakhouri Fadi is 92.25. + The average score of Feng Hanying is 88. + The average score of Garcia Hugo is 85.75. + The average score of Tucker Lance is 81.75. + The average score of Adams Terry is 85.25. + The average score of Zabokritski Eugene is 83. + The average score of Tucker Michael is 92. + */ + // + + // + // Merge the data sources by using an anonymous type. + // Note the dynamic creation of a list of ints for the + // ExamScores member. We skip 1 because the first string + // in the array is the student ID, not an exam score. + var queryNamesScores2 = from nameLine in names + let splitName = nameLine.Split(',') + from scoreLine in scores + let splitScoreLine = scoreLine.Split(',') + where Convert.ToInt32(splitName[2]) == Convert.ToInt32(splitScoreLine[0]) + select (FirstName: splitName[0], + LastName: splitName[1], + ExamScores: (from scoreAsText in splitScoreLine.Skip(1) + select Convert.ToInt32(scoreAsText)) + .ToList() + ); + + // Display each student's name and exam score average. + foreach (var student in queryNamesScores2) + { + Console.WriteLine($"The average score of {student.FirstName} {student.LastName} is {student.ExamScores.Average()}."); + } + // +} + +static void ArghArrayList() +{ + // + ArrayList arrList = new ArrayList(); + arrList.Add( + new Student + ( + FirstName: "Svetlana", + LastName: "Omelchenko", + ExamScores: new int[] { 98, 92, 81, 60 } + )); + arrList.Add( + new Student + ( + FirstName: "Claire", + LastName: "O’Donnell", + ExamScores: new int[] { 75, 84, 91, 39 } + )); + arrList.Add( + new Student + ( + FirstName: "Sven", + LastName: "Mortensen", + ExamScores: new int[] { 88, 94, 65, 91 } + )); + arrList.Add( + new Student + ( + FirstName: "Cesar", + LastName: "Garcia", + ExamScores: new int[] { 97, 89, 85, 82 } + )); + + var query = from Student student in arrList + where student.ExamScores[0] > 95 + select student; + + foreach (Student s in query) + Console.WriteLine(s.LastName + ": " + s.ExamScores[0]); + // +} +public record Student(string FirstName, string LastName, int[] ExamScores, int ID=0); diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/csv/names.csv b/docs/csharp/linq/snippets/HowToCollections/names.csv similarity index 80% rename from samples/snippets/csharp/concepts/linq/LinqSamples/csv/names.csv rename to docs/csharp/linq/snippets/HowToCollections/names.csv index 28d0f25338fc4..e09b633cdef64 100644 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/csv/names.csv +++ b/docs/csharp/linq/snippets/HowToCollections/names.csv @@ -1,4 +1,4 @@ -Omelchenko,Svetlana,111 +Omelchenko,Svetlana,111 O'Donnell,Claire,112 Mortensen,Sven,113 Garcia,Cesar,114 @@ -9,4 +9,4 @@ Garcia,Hugo,118 Tucker,Lance,119 Adams,Terry,120 Zabokritski,Eugene,121 -Tucker,Michael,122 \ No newline at end of file +Tucker,Michael,122 diff --git a/docs/csharp/linq/snippets/HowToCollections/names1.txt b/docs/csharp/linq/snippets/HowToCollections/names1.txt new file mode 100644 index 0000000000000..967b582363e2c --- /dev/null +++ b/docs/csharp/linq/snippets/HowToCollections/names1.txt @@ -0,0 +1,10 @@ +Bankov, Peter +Holm, Michael +Garcia, Hugo +Potra, Cristina +Noriega, Fabricio +Aw, Kam Foo +Beebe, Ann +Toyoshima, Tim +Guy, Wey Yuan +Garcia, Debra diff --git a/docs/csharp/linq/snippets/HowToCollections/names2.txt b/docs/csharp/linq/snippets/HowToCollections/names2.txt new file mode 100644 index 0000000000000..fc5955beecc9c --- /dev/null +++ b/docs/csharp/linq/snippets/HowToCollections/names2.txt @@ -0,0 +1,10 @@ +Liu, Jinghao +Bankov, Peter +Holm, Michael +Garcia, Hugo +Beebe, Ann +Gilchrist, Beth +Myrcha, Jacek +Giakoumakis, Leo +McLin, Nkenge +El Yassir, Mehdi diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/csv/scores.csv b/docs/csharp/linq/snippets/HowToCollections/scores.csv similarity index 82% rename from samples/snippets/csharp/concepts/linq/LinqSamples/csv/scores.csv rename to docs/csharp/linq/snippets/HowToCollections/scores.csv index c7caecd9e2249..430faf95ad2dd 100644 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/csv/scores.csv +++ b/docs/csharp/linq/snippets/HowToCollections/scores.csv @@ -1,4 +1,4 @@ -111, 97, 92, 81, 60 +111, 97, 92, 81, 60 112, 75, 84, 91, 39 113, 88, 94, 65, 91 114, 97, 89, 85, 82 @@ -9,4 +9,4 @@ 119, 68, 79, 88, 92 120, 99, 82, 81, 79 121, 96, 85, 91, 60 -122, 94, 92, 91, 91 \ No newline at end of file +122, 94, 92, 91, 91 diff --git a/docs/csharp/linq/snippets/linq-index/GroupByContiguousKeys.cs b/docs/csharp/linq/snippets/HowToExtend/GroupByContiguousKeys.cs similarity index 100% rename from docs/csharp/linq/snippets/linq-index/GroupByContiguousKeys.cs rename to docs/csharp/linq/snippets/HowToExtend/GroupByContiguousKeys.cs diff --git a/docs/csharp/programming-guide/concepts/linq/snippets/extensions/linq.csproj b/docs/csharp/linq/snippets/HowToExtend/HowToExtend.csproj similarity index 66% rename from docs/csharp/programming-guide/concepts/linq/snippets/extensions/linq.csproj rename to docs/csharp/linq/snippets/HowToExtend/HowToExtend.csproj index ddb1b95b31479..238dbed6f0319 100644 --- a/docs/csharp/programming-guide/concepts/linq/snippets/extensions/linq.csproj +++ b/docs/csharp/linq/snippets/HowToExtend/HowToExtend.csproj @@ -1,10 +1,9 @@ - + Exe net8.0 + enable enable - true - diff --git a/docs/csharp/programming-guide/concepts/linq/snippets/extensions/LinqExtensions.cs b/docs/csharp/linq/snippets/HowToExtend/LinqExtensions.cs similarity index 100% rename from docs/csharp/programming-guide/concepts/linq/snippets/extensions/LinqExtensions.cs rename to docs/csharp/linq/snippets/HowToExtend/LinqExtensions.cs diff --git a/docs/csharp/linq/snippets/HowToExtend/Program.cs b/docs/csharp/linq/snippets/HowToExtend/Program.cs new file mode 100644 index 0000000000000..15260eeec3cd6 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToExtend/Program.cs @@ -0,0 +1,86 @@ +using Custom.Linq.Extensions; + +Console.WriteLine("MedianUsage"); +MedianUsage(); +Console.WriteLine(); +Console.WriteLine("OverloadUsage"); +OverloadUsage(); +Console.WriteLine(); +Console.WriteLine("GenericUsage"); +GenericUsage(); +Console.WriteLine(); +Console.WriteLine("SequenceUsage"); +SequenceUsage(); + +static void MedianUsage() +{ + // + double[] numbers = [1.9, 2, 8, 4, 5.7, 6, 7.2, 0]; + var query = numbers.Median(); + + Console.WriteLine($"double: Median = {query}"); + // This code produces the following output: + // double: Median = 4.85 + // +} +static void OverloadUsage() +{ + // + double[] numbers1 = [1.9, 2, 8, 4, 5.7, 6, 7.2, 0]; + var query1 = numbers1.Median(); + + Console.WriteLine($"double: Median = {query1}"); + + int[] numbers2 = [1, 2, 3, 4, 5]; + var query2 = numbers2.Median(); + + Console.WriteLine($"int: Median = {query2}"); + // This code produces the following output: + // double: Median = 4.85 + // int: Median = 3 + // +} + +static void GenericUsage() +{ + // + int[] numbers3 = [1, 2, 3, 4, 5]; + + /* + You can use the num => num lambda expression as a parameter for the Median method + so that the compiler will implicitly convert its value to double. + If there is no implicit conversion, the compiler will display an error message. + */ + var query3 = numbers3.Median(num => num); + + Console.WriteLine($"int: Median = {query3}"); + + string[] numbers4 = ["one", "two", "three", "four", "five"]; + + // With the generic overload, you can also use numeric properties of objects. + var query4 = numbers4.Median(str => str.Length); + + Console.WriteLine($"string: Median = {query4}"); + // This code produces the following output: + // int: Median = 3 + // string: Median = 4 + // +} + +static void SequenceUsage() +{ + // + string[] strings = ["a", "b", "c", "d", "e"]; + + var query5 = strings.AlternateElements(); + + foreach (var element in query5) + { + Console.WriteLine(element); + } + // This code produces the following output: + // a + // c + // e + // +} diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/CompareDirectoryContents.cs b/docs/csharp/linq/snippets/HowToFilesAndDirectories/CompareDirectoryContents.cs new file mode 100644 index 0000000000000..752f8c9f67990 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/CompareDirectoryContents.cs @@ -0,0 +1,99 @@ +namespace HowToFilesAndDirectories; + +public class CompareDirectoryContents +{ + // + // This implementation defines a very simple comparison + // between two FileInfo objects. It only compares the name + // of the files being compared and their length in bytes. + class FileCompare : IEqualityComparer + { + public bool Equals(FileInfo? f1, FileInfo? f2) + { + return (f1?.Name == f2?.Name && + f1?.Length == f2?.Length); + } + + // Return a hash that reflects the comparison criteria. According to the + // rules for IEqualityComparer, if Equals is true, then the hash codes must + // also be equal. Because equality as defined here is a simple value equality, not + // reference identity, it is possible that two or more objects will produce the same + // hash code. + public int GetHashCode(FileInfo fi) + { + string s = $"{fi.Name}{fi.Length}"; + return s.GetHashCode(); + } + } + + public static void CompareDirectories() + { + string pathA = """C:\Program Files\dotnet\sdk\8.0.104"""; + string pathB = """C:\Program Files\dotnet\sdk\8.0.204"""; + + DirectoryInfo dir1 = new DirectoryInfo(pathA); + DirectoryInfo dir2 = new DirectoryInfo(pathB); + + IEnumerable list1 = dir1.GetFiles("*.*", SearchOption.AllDirectories); + IEnumerable list2 = dir2.GetFiles("*.*", SearchOption.AllDirectories); + + //A custom file comparer defined below + FileCompare myFileCompare = new FileCompare(); + + // This query determines whether the two folders contain + // identical file lists, based on the custom file comparer + // that is defined in the FileCompare class. + // The query executes immediately because it returns a bool. + bool areIdentical = list1.SequenceEqual(list2, myFileCompare); + + if (areIdentical == true) + { + Console.WriteLine("the two folders are the same"); + } + else + { + Console.WriteLine("The two folders are not the same"); + } + + // Find the common files. It produces a sequence and doesn't + // execute until the foreach statement. + var queryCommonFiles = list1.Intersect(list2, myFileCompare); + + if (queryCommonFiles.Any()) + { + Console.WriteLine($"The following files are in both folders (total number = {queryCommonFiles.Count()}):"); + foreach (var v in queryCommonFiles.Take(10)) + { + Console.WriteLine(v.Name); //shows which items end up in result list + } + } + else + { + Console.WriteLine("There are no common files in the two folders."); + } + + // Find the set difference between the two folders. + var queryList1Only = (from file in list1 + select file) + .Except(list2, myFileCompare); + + Console.WriteLine(); + Console.WriteLine($"The following files are in list1 but not list2 (total number = {queryList1Only.Count()}):"); + foreach (var v in queryList1Only.Take(10)) + { + Console.WriteLine(v.FullName); + } + + var queryList2Only = (from file in list2 + select file) + .Except(list1, myFileCompare); + + Console.WriteLine(); + Console.WriteLine($"The following files are in list2 but not list1 (total number = {queryList2Only.Count()}:"); + foreach (var v in queryList2Only.Take(10)) + { + Console.WriteLine(v.FullName); + } + } + // +} diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/DuplicateFileQuery.cs b/docs/csharp/linq/snippets/HowToFilesAndDirectories/DuplicateFileQuery.cs new file mode 100644 index 0000000000000..6e7ac3cefe908 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/DuplicateFileQuery.cs @@ -0,0 +1,84 @@ +namespace HowToFilesAndDirectories; +public static class DuplicateFileQuery +{ + public static void Examples() + { + Console.WriteLine("Query duplicates:"); + QueryDuplicateNames(); + + Console.WriteLine(); + Console.WriteLine("Query duplicates 2:"); + QueryDuplicateFileInfo(); + } + + static void QueryDuplicateNames() + { + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + DirectoryInfo dir = new DirectoryInfo(startFolder); + + IEnumerable fileList = dir.GetFiles("*.*", SearchOption.AllDirectories); + + // used in WriteLine to keep the lines shorter + int charsToSkip = startFolder.Length; + + // var can be used for convenience with groups. + var queryDupNames = from file in fileList + group file.FullName.Substring(charsToSkip) by file.Name into fileGroup + where fileGroup.Count() > 1 + select fileGroup; + + foreach (var queryDup in queryDupNames.Take(20)) + { + Console.WriteLine($"Filename = {(queryDup.Key.ToString() == string.Empty ? "[none]" : queryDup.Key.ToString())}"); + + foreach (var fileName in queryDup.Take(10)) + { + Console.WriteLine($"\t{fileName}"); + } + } + // + } + + static void QueryDuplicateFileInfo() + { + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + // Make the lines shorter for the console display + int charsToSkip = startFolder.Length; + + // Take a snapshot of the file system. + DirectoryInfo dir = new DirectoryInfo(startFolder); + IEnumerable fileList = dir.GetFiles("*.*", SearchOption.AllDirectories); + + // Note the use of a compound key. Files that match + // all three properties belong to the same group. + // A named type is used to enable the query to be + // passed to another method. Anonymous types can also be used + // for composite keys but cannot be passed across method boundaries + // + var queryDupFiles = from file in fileList + group file.FullName.Substring(charsToSkip) by + (Name: file.Name, LastWriteTime: file.LastWriteTime, Length: file.Length ) + into fileGroup + where fileGroup.Count() > 1 + select fileGroup; + + foreach (var queryDup in queryDupFiles.Take(20)) + { + Console.WriteLine($"Filename = {(queryDup.Key.ToString() == string.Empty ? "[none]" : queryDup.Key.ToString())}"); + + foreach (var fileName in queryDup) + { + Console.WriteLine($"\t{fileName}"); + } + } + } + // +} diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/HowToFilesAndDirectories.csproj b/docs/csharp/linq/snippets/HowToFilesAndDirectories/HowToFilesAndDirectories.csproj new file mode 100644 index 0000000000000..37f94878a8782 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/HowToFilesAndDirectories.csproj @@ -0,0 +1,34 @@ + + + + Exe + net8.0 + enable + enable + + + + + + + + + + + + PreserveNewest + + + PreserveNewest + + + PreserveNewest + + + PreserveNewest + + + PreserveNewest + + + diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/Program.cs b/docs/csharp/linq/snippets/HowToFilesAndDirectories/Program.cs new file mode 100644 index 0000000000000..551ddf1b0f0c2 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/Program.cs @@ -0,0 +1,345 @@ +using HowToFilesAndDirectories; + +Console.WriteLine("Find files by extension:"); +FindFilesByExtension(); +Console.WriteLine(); +Console.WriteLine("Group files by extension:"); +GroupFilesByExtension(); +Console.WriteLine(); +Console.WriteLine("Query by file size:"); +QueryByFileSize(); +Console.WriteLine(); +Console.WriteLine("Query duplicates:"); +DuplicateFileQuery.Examples(); +Console.WriteLine(); +Console.WriteLine("Compare directory contents:"); +CompareDirectoryContents.CompareDirectories(); +Console.WriteLine(); +Console.WriteLine("Search file contents:"); +QueryTextContent(); + +Console.WriteLine(); +Console.WriteLine("Update file content:"); +UpdateFileContent(); + +Console.WriteLine(); +Console.WriteLine("Split file into groups"); +SplitFileIntoGroups(); + +Console.WriteLine(); +Console.WriteLine("Join dissimilar files"); +JoinDissimilarFiles(); + +Console.WriteLine(); +Console.WriteLine("Sum Spreadsheet columns"); +SumColumns.SumCSVColumns("scores.csv"); + +static void FindFilesByExtension() +{ + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + DirectoryInfo dir = new DirectoryInfo(startFolder); + var fileList = dir.GetFiles("*.*", SearchOption.AllDirectories); + + var fileQuery = from file in fileList + where file.Extension == ".txt" + orderby file.Name + select file; + + // Uncomment this block to see the full query + // foreach (FileInfo fi in fileQuery) + // { + // Console.WriteLine(fi.FullName); + // } + + var newestFile = (from file in fileQuery + orderby file.CreationTime + select new { file.FullName, file.CreationTime }) + .Last(); + + Console.WriteLine($"\r\nThe newest .txt file is {newestFile.FullName}. Creation time: {newestFile.CreationTime}"); + // +} + +// This query will sort all the files under the specified folder +// and subfolder into groups keyed by the file extension. +static void GroupFilesByExtension() +{ + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + int trimLength = startFolder.Length; + + DirectoryInfo dir = new DirectoryInfo(startFolder); + + var fileList = dir.GetFiles("*.*", SearchOption.AllDirectories); + + var queryGroupByExt = from file in fileList + group file by file.Extension.ToLower() into fileGroup + orderby fileGroup.Count(), fileGroup.Key + select fileGroup; + + // Iterate through the outer collection of groups. + foreach (var filegroup in queryGroupByExt.Take(5)) + { + Console.WriteLine($"Extension: {filegroup.Key}"); + var resultPage = filegroup.Take(20); + + //Execute the resultPage query + foreach (var f in resultPage) + { + Console.WriteLine($"\t{f.FullName.Substring(trimLength)}"); + } + Console.WriteLine(); + } + // +} + +static void QueryByFileSize() +{ + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + var fileList = Directory.GetFiles(startFolder, "*.*", SearchOption.AllDirectories); + + var fileQuery = from file in fileList + let fileLen = new FileInfo(file).Length + where fileLen > 0 + select fileLen; + + // Cache the results to avoid multiple trips to the file system. + long[] fileLengths = fileQuery.ToArray(); + + // Return the size of the largest file + long largestFile = fileLengths.Max(); + + // Return the total number of bytes in all the files under the specified folder. + long totalBytes = fileLengths.Sum(); + + Console.WriteLine($"There are {totalBytes} bytes in {fileList.Count()} files under {startFolder}"); + Console.WriteLine($"The largest file is {largestFile} bytes."); + // + + // + // Return the FileInfo object for the largest file + // by sorting and selecting from beginning of list + FileInfo longestFile = (from file in fileList + let fileInfo = new FileInfo(file) + where fileInfo.Length > 0 + orderby fileInfo.Length descending + select fileInfo + ).First(); + + Console.WriteLine($"The largest file under {startFolder} is {longestFile.FullName} with a length of {longestFile.Length} bytes"); + + //Return the FileInfo of the smallest file + FileInfo smallestFile = (from file in fileList + let fileInfo = new FileInfo(file) + where fileInfo.Length > 0 + orderby fileInfo.Length ascending + select fileInfo + ).First(); + + Console.WriteLine($"The smallest file under {startFolder} is {smallestFile.FullName} with a length of {smallestFile.Length} bytes"); + + //Return the FileInfos for the 10 largest files + var queryTenLargest = (from file in fileList + let fileInfo = new FileInfo(file) + let len = fileInfo.Length + orderby len descending + select fileInfo + ).Take(10); + + Console.WriteLine($"The 10 largest files under {startFolder} are:"); + + foreach (var v in queryTenLargest) + { + Console.WriteLine($"{v.FullName}: {v.Length} bytes"); + } + + // Group the files according to their size, leaving out + // files that are less than 200000 bytes. + var querySizeGroups = from file in fileList + let fileInfo = new FileInfo(file) + let len = fileInfo.Length + where len > 0 + group fileInfo by (len / 100000) into fileGroup + where fileGroup.Key >= 2 + orderby fileGroup.Key descending + select fileGroup; + + foreach (var filegroup in querySizeGroups) + { + Console.WriteLine($"{filegroup.Key}00000"); + foreach (var item in filegroup) + { + Console.WriteLine($"\t{item.Name}: {item.Length}"); + } + } + // +} + +static void QueryTextContent() +{ + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + DirectoryInfo dir = new DirectoryInfo(startFolder); + + var fileList = dir.GetFiles("*.*", SearchOption.AllDirectories); + + string searchTerm = "change"; + + var queryMatchingFiles = from file in fileList + where file.Extension == ".txt" + let fileText = File.ReadAllText(file.FullName) + where fileText.Contains(searchTerm) + select file.FullName; + + // Execute the query. + Console.WriteLine($"""The term "{searchTerm}" was found in:"""); + foreach (string filename in queryMatchingFiles) + { + Console.WriteLine(filename); + } + // +} + +static void UpdateFileContent() +{ + // + string[] lines = File.ReadAllLines("spreadsheet1.csv"); + + // Create the query. Put field 2 first, then + // reverse and combine fields 0 and 1 from the old field + IEnumerable query = from line in lines + let fields = line.Split(',') + orderby fields[2] + select $"{fields[2]}, {fields[1]} {fields[0]}"; + + File.WriteAllLines("spreadsheet2.csv", query.ToArray()); + + /* Output to spreadsheet2.csv: + 111, Svetlana Omelchenko + 112, Claire O'Donnell + 113, Sven Mortensen + 114, Cesar Garcia + 115, Debra Garcia + 116, Fadi Fakhouri + 117, Hanying Feng + 118, Hugo Garcia + 119, Lance Tucker + 120, Terry Adams + 121, Eugene Zabokritski + 122, Michael Tucker + */ + // +} + +static void SplitFileIntoGroups() +{ + // + string[] fileA = File.ReadAllLines("names1.txt"); + string[] fileB = File.ReadAllLines("names2.txt"); + + // Concatenate and remove duplicate names + var mergeQuery = fileA.Union(fileB); + + // Group the names by the first letter in the last name. + var groupQuery = from name in mergeQuery + let n = name.Split(',')[0] + group name by n[0] into g + orderby g.Key + select g; + + foreach (var g in groupQuery) + { + string fileName = $"testFile_{g.Key}.txt"; + + Console.WriteLine(g.Key); + + using StreamWriter sw = new StreamWriter(fileName); + foreach (var item in g) + { + sw.WriteLine(item); + // Output to console for example purposes. + Console.WriteLine($" {item}"); + } + } + /* Output: + A + Aw, Kam Foo + B + Bankov, Peter + Beebe, Ann + E + El Yassir, Mehdi + G + Garcia, Hugo + Guy, Wey Yuan + Garcia, Debra + Gilchrist, Beth + Giakoumakis, Leo + H + Holm, Michael + L + Liu, Jinghao + M + Myrcha, Jacek + McLin, Nkenge + N + Noriega, Fabricio + P + Potra, Cristina + T + Toyoshima, Tim + */ + // +} + +static void JoinDissimilarFiles() +{ + // + string[] names = File.ReadAllLines(@"names.csv"); + string[] scores = File.ReadAllLines(@"scores.csv"); + + var scoreQuery = from name in names + let nameFields = name.Split(',') + from id in scores + let scoreFields = id.Split(',') + where Convert.ToInt32(nameFields[2]) == Convert.ToInt32(scoreFields[0]) + select $"{nameFields[0]},{scoreFields[1]},{scoreFields[2]},{scoreFields[3]},{scoreFields[4]}"; + + Console.WriteLine("\r\nMerge two spreadsheets:"); + foreach (string item in scoreQuery) + { + Console.WriteLine(item); + } + Console.WriteLine("{0} total names in list", scoreQuery.Count()); + /* Output: + Merge two spreadsheets: + Omelchenko, 97, 92, 81, 60 + O'Donnell, 75, 84, 91, 39 + Mortensen, 88, 94, 65, 91 + Garcia, 97, 89, 85, 82 + Garcia, 35, 72, 91, 70 + Fakhouri, 99, 86, 90, 94 + Feng, 93, 92, 80, 87 + Garcia, 92, 90, 83, 78 + Tucker, 68, 79, 88, 92 + Adams, 99, 82, 81, 79 + Zabokritski, 96, 85, 91, 60 + Tucker, 94, 92, 91, 91 + 12 total names in list + */ + // +} diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/SumColumns.cs b/docs/csharp/linq/snippets/HowToFilesAndDirectories/SumColumns.cs new file mode 100644 index 0000000000000..a8db8b22bc761 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/SumColumns.cs @@ -0,0 +1,117 @@ +namespace HowToFilesAndDirectories; + +// +public class SumColumns +{ + public static void SumCSVColumns(string fileName) + { + string[] lines = File.ReadAllLines(fileName); + + // Specifies the column to compute. + int exam = 3; + + // Spreadsheet format: + // Student ID Exam#1 Exam#2 Exam#3 Exam#4 + // 111, 97, 92, 81, 60 + + // Add one to exam to skip over the first column, + // which holds the student ID. + SingleColumn(lines, exam + 1); + Console.WriteLine(); + MultiColumns(lines); + } + + static void SingleColumn(IEnumerable strs, int examNum) + { + Console.WriteLine("Single Column Query:"); + + // Parameter examNum specifies the column to + // run the calculations on. This value could be + // passed in dynamically at run time. + + // Variable columnQuery is an IEnumerable. + // The following query performs two steps: + // 1) use Split to break each row (a string) into an array + // of strings, + // 2) convert the element at position examNum to an int + // and select it. + var columnQuery = from line in strs + let elements = line.Split(',') + select Convert.ToInt32(elements[examNum]); + + // Execute the query and cache the results to improve + // performance. This is helpful only with very large files. + var results = columnQuery.ToList(); + + // Perform aggregate calculations Average, Max, and + // Min on the column specified by examNum. + double average = results.Average(); + int max = results.Max(); + int min = results.Min(); + + Console.WriteLine($"Exam #{examNum}: Average:{average:##.##} High Score:{max} Low Score:{min}"); + } + + static void MultiColumns(IEnumerable strs) + { + Console.WriteLine("Multi Column Query:"); + + // Create a query, multiColQuery. Explicit typing is used + // to make clear that, when executed, multiColQuery produces + // nested sequences. However, you get the same results by + // using 'var'. + + // The multiColQuery query performs the following steps: + // 1) use Split to break each row (a string) into an array + // of strings, + // 2) use Skip to skip the "Student ID" column, and store the + // rest of the row in scores. + // 3) convert each score in the current row from a string to + // an int, and select that entire sequence as one row + // in the results. + var multiColQuery = from line in strs + let elements = line.Split(',') + let scores = elements.Skip(1) + select (from str in scores + select Convert.ToInt32(str)); + + // Execute the query and cache the results to improve + // performance. + // ToArray could be used instead of ToList. + var results = multiColQuery.ToList(); + + // Find out how many columns you have in results. + int columnCount = results[0].Count(); + + // Perform aggregate calculations Average, Max, and + // Min on each column. + // Perform one iteration of the loop for each column + // of scores. + // You can use a for loop instead of a foreach loop + // because you already executed the multiColQuery + // query by calling ToList. + for (int column = 0; column < columnCount; column++) + { + var results2 = from row in results + select row.ElementAt(column); + double average = results2.Average(); + int max = results2.Max(); + int min = results2.Min(); + + // Add one to column because the first exam is Exam #1, + // not Exam #0. + Console.WriteLine($"Exam #{column + 1} Average: {average:##.##} High Score: {max} Low Score: {min}"); + } + } +} +/* Output: + Single Column Query: + Exam #4: Average:76.92 High Score:94 Low Score:39 + + Multi Column Query: + Exam #1 Average: 86.08 High Score: 99 Low Score: 35 + Exam #2 Average: 86.42 High Score: 94 Low Score: 72 + Exam #3 Average: 84.75 High Score: 91 Low Score: 65 + Exam #4 Average: 76.92 High Score: 94 Low Score: 39 + */ +// diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/names.csv b/docs/csharp/linq/snippets/HowToFilesAndDirectories/names.csv new file mode 100644 index 0000000000000..e09b633cdef64 --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/names.csv @@ -0,0 +1,12 @@ +Omelchenko,Svetlana,111 +O'Donnell,Claire,112 +Mortensen,Sven,113 +Garcia,Cesar,114 +Garcia,Debra,115 +Fakhouri,Fadi,116 +Feng,Hanying,117 +Garcia,Hugo,118 +Tucker,Lance,119 +Adams,Terry,120 +Zabokritski,Eugene,121 +Tucker,Michael,122 diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/names1.txt b/docs/csharp/linq/snippets/HowToFilesAndDirectories/names1.txt new file mode 100644 index 0000000000000..967b582363e2c --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/names1.txt @@ -0,0 +1,10 @@ +Bankov, Peter +Holm, Michael +Garcia, Hugo +Potra, Cristina +Noriega, Fabricio +Aw, Kam Foo +Beebe, Ann +Toyoshima, Tim +Guy, Wey Yuan +Garcia, Debra diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/names2.txt b/docs/csharp/linq/snippets/HowToFilesAndDirectories/names2.txt new file mode 100644 index 0000000000000..fc5955beecc9c --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/names2.txt @@ -0,0 +1,10 @@ +Liu, Jinghao +Bankov, Peter +Holm, Michael +Garcia, Hugo +Beebe, Ann +Gilchrist, Beth +Myrcha, Jacek +Giakoumakis, Leo +McLin, Nkenge +El Yassir, Mehdi diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/scores.csv b/docs/csharp/linq/snippets/HowToFilesAndDirectories/scores.csv new file mode 100644 index 0000000000000..430faf95ad2dd --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/scores.csv @@ -0,0 +1,12 @@ +111, 97, 92, 81, 60 +112, 75, 84, 91, 39 +113, 88, 94, 65, 91 +114, 97, 89, 85, 82 +115, 35, 72, 91, 70 +116, 99, 86, 90, 94 +117, 93, 92, 80, 87 +118, 92, 90, 83, 78 +119, 68, 79, 88, 92 +120, 99, 82, 81, 79 +121, 96, 85, 91, 60 +122, 94, 92, 91, 91 diff --git a/docs/csharp/linq/snippets/HowToFilesAndDirectories/spreadsheet1.csv b/docs/csharp/linq/snippets/HowToFilesAndDirectories/spreadsheet1.csv new file mode 100644 index 0000000000000..ca74dec65b39b --- /dev/null +++ b/docs/csharp/linq/snippets/HowToFilesAndDirectories/spreadsheet1.csv @@ -0,0 +1,12 @@ +Adams,Terry,120 +Fakhouri,Fadi,116 +Feng,Hanying,117 +Garcia,Cesar,114 +Garcia,Debra,115 +Garcia,Hugo,118 +Mortensen,Sven,113 +O'Donnell,Claire,112 +Omelchenko,Svetlana,111 +Tucker,Lance,119 +Tucker,Michael,122 +Zabokritski,Eugene,121 diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/LinqSamples.csproj b/docs/csharp/linq/snippets/HowToStrings/HowToStrings.csproj similarity index 60% rename from samples/snippets/csharp/concepts/linq/LinqSamples/LinqSamples.csproj rename to docs/csharp/linq/snippets/HowToStrings/HowToStrings.csproj index f2c4d79027c0c..653a39fe71043 100644 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/LinqSamples.csproj +++ b/docs/csharp/linq/snippets/HowToStrings/HowToStrings.csproj @@ -1,4 +1,4 @@ - + Exe @@ -8,12 +8,13 @@ - - PreserveNewest - - + + + + + PreserveNewest - + diff --git a/docs/csharp/linq/snippets/HowToStrings/Program.cs b/docs/csharp/linq/snippets/HowToStrings/Program.cs new file mode 100644 index 0000000000000..9227d92725a2c --- /dev/null +++ b/docs/csharp/linq/snippets/HowToStrings/Program.cs @@ -0,0 +1,215 @@ + +Console.WriteLine("Chars in a string"); +CharsInAString(); +Console.WriteLine(); +Console.WriteLine("Count words in a string"); +CountWordsInAString(); +Console.WriteLine(); +Console.WriteLine("Sort strings"); +SortStrings(); +Console.WriteLine(); +Console.WriteLine("Find sentences"); +FindSentences(); +QueryWithRegEx(); + +static void CharsInAString() +{ + // + string aString = "ABCDE99F-J74-12-89A"; + + // Select only those characters that are numbers + var stringQuery = from ch in aString + where Char.IsDigit(ch) + select ch; + + // Execute the query + foreach (char c in stringQuery) + Console.Write(c + " "); + + // Call the Count method on the existing query. + int count = stringQuery.Count(); + Console.WriteLine($"Count = {count}"); + + // Select all characters before the first '-' + var stringQuery2 = aString.TakeWhile(c => c != '-'); + + // Execute the second query + foreach (char c in stringQuery2) + Console.Write(c); + /* Output: + Output: 9 9 7 4 1 2 8 9 + Count = 8 + ABCDE99F + */ + // +} + +static void CountWordsInAString() +{ + // + string text = """ + Historically, the world of data and the world of objects + have not been well integrated. Programmers work in C# or Visual Basic + and also in SQL or XQuery. On the one side are concepts such as classes, + objects, fields, inheritance, and .NET APIs. On the other side + are tables, columns, rows, nodes, and separate languages for dealing with + them. Data types often require translation between the two worlds; there are + different standard functions. Because the object world has no notion of query, a + query can only be represented as a string without compile-time type checking or + IntelliSense support in the IDE. Transferring data from SQL tables or XML trees to + objects in memory is often tedious and error-prone. + """; + + string searchTerm = "data"; + + //Convert the string into an array of words + char[] separators = ['.', '?', '!', ' ', ';', ':', ',']; + string[] source = text.Split(separators, StringSplitOptions.RemoveEmptyEntries); + + // Create the query. Use the InvariantCultureIgnoreCase comparison to match "data" and "Data" + var matchQuery = from word in source + where word.Equals(searchTerm, StringComparison.InvariantCultureIgnoreCase) + select word; + + // Count the matches, which executes the query. + int wordCount = matchQuery.Count(); + Console.WriteLine($"""{wordCount} occurrences(s) of the search term "{searchTerm}" were found."""); + /* Output: + 3 occurrences(s) of the search term "data" were found. + */ + // +} + +static void SortStrings() +{ + // + // Create an IEnumerable data source + string[] scores = File.ReadAllLines("scores.csv"); + + // Change this to any value from 0 to 4. + int sortField = 1; + + Console.WriteLine($"Sorted highest to lowest by field [{sortField}]:"); + + // Split the string and sort on field[num] + var scoreQuery = from line in scores + let fields = line.Split(',') + orderby fields[sortField] descending + select line; + + foreach (string str in scoreQuery) + { + Console.WriteLine(str); + } + /* Output (if sortField == 1): + Sorted highest to lowest by field [1]: + 116, 99, 86, 90, 94 + 120, 99, 82, 81, 79 + 111, 97, 92, 81, 60 + 114, 97, 89, 85, 82 + 121, 96, 85, 91, 60 + 122, 94, 92, 91, 91 + 117, 93, 92, 80, 87 + 118, 92, 90, 83, 78 + 113, 88, 94, 65, 91 + 112, 75, 84, 91, 39 + 119, 68, 79, 88, 92 + 115, 35, 72, 91, 70 + */ + // +} + +static void FindSentences() +{ + // + string text = """ + Historically, the world of data and the world of objects + have not been well integrated. Programmers work in C# or Visual Basic + and also in SQL or XQuery. On the one side are concepts such as classes, + objects, fields, inheritance, and .NET APIs. On the other side + are tables, columns, rows, nodes, and separate languages for dealing with + them. Data types often require translation between the two worlds; there are + different standard functions. Because the object world has no notion of query, a + query can only be represented as a string without compile-time type checking or + IntelliSense support in the IDE. Transferring data from SQL tables or XML trees to + objects in memory is often tedious and error-prone. + """; + + // Split the text block into an array of sentences. + string[] sentences = text.Split(['.', '?', '!']); + + // Define the search terms. This list could also be dynamically populated at run time. + string[] wordsToMatch = [ "Historically", "data", "integrated" ]; + + // Find sentences that contain all the terms in the wordsToMatch array. + // Note that the number of terms to match is not specified at compile time. + char[] separators = ['.', '?', '!', ' ', ';', ':', ',']; + var sentenceQuery = from sentence in sentences + let w = sentence.Split(separators,StringSplitOptions.RemoveEmptyEntries) + where w.Distinct().Intersect(wordsToMatch).Count() == wordsToMatch.Count() + select sentence; + + foreach (string str in sentenceQuery) + { + Console.WriteLine(str); + } + /* Output: + Historically, the world of data and the world of objects have not been well integrated + */ + // +} + +static void QueryWithRegEx() +{ + // + string startFolder = """C:\Program Files\dotnet\sdk"""; + // Or + // string startFolder = "/usr/local/share/dotnet/sdk"; + + // Take a snapshot of the file system. + var fileList = from file in Directory.GetFiles(startFolder, "*.*", SearchOption.AllDirectories) + let fileInfo = new FileInfo(file) + select fileInfo; + + // Create the regular expression to find all things "Visual". + System.Text.RegularExpressions.Regex searchTerm = + new System.Text.RegularExpressions.Regex(@"microsoft.net.(sdk|workload)"); + + // Search the contents of each .htm file. + // Remove the where clause to find even more matchedValues! + // This query produces a list of files where a match + // was found, and a list of the matchedValues in that file. + // Note: Explicit typing of "Match" in select clause. + // This is required because MatchCollection is not a + // generic IEnumerable collection. + var queryMatchingFiles = + from file in fileList + where file.Extension == ".txt" + let fileText = File.ReadAllText(file.FullName) + let matches = searchTerm.Matches(fileText) + where matches.Count > 0 + select new + { + name = file.FullName, + matchedValues = from System.Text.RegularExpressions.Match match in matches + select match.Value + }; + + // Execute the query. + Console.WriteLine($"""The term "{searchTerm}" was found in:"""); + + foreach (var v in queryMatchingFiles) + { + // Trim the path a bit, then write + // the file name in which a match was found. + string s = v.name.Substring(startFolder.Length - 1); + Console.WriteLine(s); + + // For this file, write out all the matching strings + foreach (var v2 in v.matchedValues) + { + Console.WriteLine($" {v2}"); + } + } + // +} diff --git a/docs/csharp/linq/snippets/HowToStrings/scores.csv b/docs/csharp/linq/snippets/HowToStrings/scores.csv new file mode 100644 index 0000000000000..430faf95ad2dd --- /dev/null +++ b/docs/csharp/linq/snippets/HowToStrings/scores.csv @@ -0,0 +1,12 @@ +111, 97, 92, 81, 60 +112, 75, 84, 91, 39 +113, 88, 94, 65, 91 +114, 97, 89, 85, 82 +115, 35, 72, 91, 70 +116, 99, 86, 90, 94 +117, 93, 92, 80, 87 +118, 92, 90, 83, 78 +119, 68, 79, 88, 92 +120, 99, 82, 81, 79 +121, 96, 85, 91, 60 +122, 94, 92, 91, 91 diff --git a/docs/csharp/linq/snippets/linq-index/Index.cs b/docs/csharp/linq/snippets/linq-index/Index.cs index cd9be3d005c77..40e75198ce060 100644 --- a/docs/csharp/linq/snippets/linq-index/Index.cs +++ b/docs/csharp/linq/snippets/linq-index/Index.cs @@ -1,6 +1,6 @@ namespace LinqSamples; -public static class Index +public static class IndexClass { public static void Intro() { diff --git a/docs/csharp/linq/snippets/linq-index/Program.cs b/docs/csharp/linq/snippets/linq-index/Program.cs index 3751555cbd32d..3eb590e08be06 100644 --- a/docs/csharp/linq/snippets/linq-index/Program.cs +++ b/docs/csharp/linq/snippets/linq-index/Program.cs @@ -1,2 +1,2 @@ -// See https://aka.ms/new-console-template for more information -Console.WriteLine("Hello, World!"); + +LinqSamples.IndexClass.Intro(); diff --git a/docs/csharp/linq/standard-query-operators/filtering-data.md b/docs/csharp/linq/standard-query-operators/filtering-data.md index 95a6f30309693..65c497fb2f417 100644 --- a/docs/csharp/linq/standard-query-operators/filtering-data.md +++ b/docs/csharp/linq/standard-query-operators/filtering-data.md @@ -31,5 +31,5 @@ The equivalent query using method syntax is shown in the following code: - - [where clause](../../language-reference/keywords/where-clause.md) - [How to query an assembly's metadata with Reflection (LINQ) (C#)](../../advanced-topics/reflection-and-attributes/how-to-query-assembly-metadata-with-reflection-linq.md) -- [How to query for files with a specified attribute or name (C#)](../../programming-guide/concepts/linq/how-to-query-for-files-with-a-specified-attribute-or-name.md) -- [How to sort or filter text data by any word or field (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md) +- [How to query for files with a specified attribute or name (C#)](../how-to-query-files-and-directories.md) +- [How to sort or filter text data by any word or field (LINQ) (C#)](../how-to-query-strings.md) diff --git a/docs/csharp/linq/standard-query-operators/grouping-data.md b/docs/csharp/linq/standard-query-operators/grouping-data.md index cf98a00a22611..489b4db7a581c 100644 --- a/docs/csharp/linq/standard-query-operators/grouping-data.md +++ b/docs/csharp/linq/standard-query-operators/grouping-data.md @@ -125,5 +125,4 @@ The query in the preceding snippet can also be written using method syntax. The - - - [group clause](../../language-reference/keywords/group-clause.md) -- [How to group files by extension (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md) -- [How to split a file into many files by using groups (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md) +- [How to split a file into many files by using groups (LINQ) (C#)](../how-to-query-files-and-directories.md) diff --git a/docs/csharp/linq/standard-query-operators/index.md b/docs/csharp/linq/standard-query-operators/index.md index 0d227e132dd6e..7591b94a7ac2b 100644 --- a/docs/csharp/linq/standard-query-operators/index.md +++ b/docs/csharp/linq/standard-query-operators/index.md @@ -38,7 +38,7 @@ In a LINQ query, the first step is to specify the data source. In a LINQ query, The range variable is like the iteration variable in a `foreach` loop except that no actual iteration occurs in a query expression. When the query is executed, the range variable serves as a reference to each successive element in `customers`. Because the compiler can infer the type of `cust`, you don't have to specify it explicitly. You can introduce more range variables in a `let` clause. For more information, see [let clause](../../language-reference/keywords/let-clause.md). > [!NOTE] -> For non-generic data sources such as , the range variable must be explicitly typed. For more information, see [How to query an ArrayList with LINQ (C#)](../../programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md) and [from clause](../../language-reference/keywords/from-clause.md). +> For non-generic data sources such as , the range variable must be explicitly typed. For more information, see [How to query an ArrayList with LINQ (C#)](../how-to-query-collections.md) and [from clause](../../language-reference/keywords/from-clause.md). Once you obtain a data source, you can perform any number of operations on that data source: diff --git a/docs/csharp/linq/standard-query-operators/join-operations.md b/docs/csharp/linq/standard-query-operators/join-operations.md index 9233844aebac4..6eb4a90b34a8b 100644 --- a/docs/csharp/linq/standard-query-operators/join-operations.md +++ b/docs/csharp/linq/standard-query-operators/join-operations.md @@ -171,5 +171,5 @@ The equivalent query using method syntax is shown in the following code: - [Formulate Joins and Cross-Product Queries](../../../framework/data/adonet/sql/linq/formulate-joins-and-cross-product-queries.md) - [join clause](../../language-reference/keywords/join-clause.md) - [group clause](../../language-reference/keywords/group-clause.md) -- [How to join content from dissimilar files (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-join-content-from-dissimilar-files-linq.md) -- [How to populate object collections from multiple sources (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md) +- [How to join content from dissimilar files (LINQ) (C#)](../how-to-query-files-and-directories.md) +- [How to populate object collections from multiple sources (LINQ) (C#)](../how-to-query-collections.md) diff --git a/docs/csharp/linq/standard-query-operators/projection-operations.md b/docs/csharp/linq/standard-query-operators/projection-operations.md index 3457304ae2170..3f938bce84dc8 100644 --- a/docs/csharp/linq/standard-query-operators/projection-operations.md +++ b/docs/csharp/linq/standard-query-operators/projection-operations.md @@ -100,5 +100,5 @@ The following example compares the behavior of `Select` and `SelectMany`. The co - - [select clause](../../language-reference/keywords/select-clause.md) -- [How to populate object collections from multiple sources (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md) -- [How to split a file into many files by using groups (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md) +- [How to populate object collections from multiple sources (LINQ) (C#)](../how-to-query-collections.md) +- [How to split a file into many files by using groups (LINQ) (C#)](../how-to-query-files-and-directories.md) diff --git a/docs/csharp/linq/standard-query-operators/quantifier-operations.md b/docs/csharp/linq/standard-query-operators/quantifier-operations.md index 9d0a01e175a12..3fb420f4968c1 100644 --- a/docs/csharp/linq/standard-query-operators/quantifier-operations.md +++ b/docs/csharp/linq/standard-query-operators/quantifier-operations.md @@ -39,5 +39,5 @@ The following example uses the `Contains` to find students that scored exactly 9 ## See also - -- [Dynamically specify predicate filters at run time](../dynamically-specify-predicate-filters-at-runtime.md) -- [How to query for sentences that contain a specified set of words (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words-linq.md) +- [Dynamically specify predicate filters at run time](../get-started/write-linq-queries.md) +- [How to query for sentences that contain a specified set of words (LINQ) (C#)](../how-to-query-strings.md) diff --git a/docs/csharp/linq/standard-query-operators/set-operations.md b/docs/csharp/linq/standard-query-operators/set-operations.md index 4e07462a50949..79ff8c8f348d4 100644 --- a/docs/csharp/linq/standard-query-operators/set-operations.md +++ b/docs/csharp/linq/standard-query-operators/set-operations.md @@ -90,5 +90,4 @@ In the preceding C# code: ## See also - -- [How to combine and compare string collections (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-combine-and-compare-string-collections-linq.md) -- [How to find the set difference between two lists (LINQ) (C#)](../../programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md) +- [How to find the set difference between two lists (LINQ) (C#)](../how-to-query-collections.md) diff --git a/docs/csharp/linq/standard-query-operators/sorting-data.md b/docs/csharp/linq/standard-query-operators/sorting-data.md index 24bbfe8d1fa39..3ee99d987841e 100644 --- a/docs/csharp/linq/standard-query-operators/sorting-data.md +++ b/docs/csharp/linq/standard-query-operators/sorting-data.md @@ -73,4 +73,4 @@ The equivalent query written using method syntax is shown in the following code: - - [orderby clause](../../language-reference/keywords/orderby-clause.md) -- [How to sort or filter text data by any word or field (LINQ) (C#)](../../programming-guide/concepts/linq//how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md) +- [How to sort or filter text data by any word or field (LINQ) (C#)](../how-to-query-strings.md) diff --git a/docs/csharp/linq/store-the-results-of-a-query-in-memory.md b/docs/csharp/linq/store-the-results-of-a-query-in-memory.md deleted file mode 100644 index 3cc7217be7c2d..0000000000000 --- a/docs/csharp/linq/store-the-results-of-a-query-in-memory.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Store the results of a query in memory -description: How to store results. -ms.date: 11/30/2016 -ms.assetid: 5b863961-1750-4cf9-9607-acea5054d15a ---- -# Store the results of a query in memory - -A query is basically a set of instructions for how to retrieve and organize data. Queries are executed lazily, as each subsequent item in the result is requested. When you use `foreach` to iterate the results, items are returned as accessed. To evaluate a query and store its results without executing a `foreach` loop, just call one of the following methods on the query variable: - -- - -- - -- - -- - - We recommend that when you store the query results, you assign the returned collection object to a new variable as shown in the following example: - -## Example - -:::code language="csharp" source="../../../samples/snippets/csharp/concepts/linq/LinqSamples/StoreResultsOfQueryInMemory.cs" id="store_results_of_query_in_memory_1"::: - -## See also - -- [Language Integrated Query (LINQ)](index.md) diff --git a/docs/csharp/misc/cs1934.md b/docs/csharp/misc/cs1934.md index babae51844d0a..61ec7638ab322 100644 --- a/docs/csharp/misc/cs1934.md +++ b/docs/csharp/misc/cs1934.md @@ -43,4 +43,4 @@ static class Test ## See also -- [How to query an ArrayList with LINQ](../programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md) +- [How to query an ArrayList with LINQ](../linq/how-to-query-collections.md) diff --git a/docs/csharp/programming-guide/classes-and-structs/object-and-collection-initializers.md b/docs/csharp/programming-guide/classes-and-structs/object-and-collection-initializers.md index aa6647537964c..7b557a2e2e713 100644 --- a/docs/csharp/programming-guide/classes-and-structs/object-and-collection-initializers.md +++ b/docs/csharp/programming-guide/classes-and-structs/object-and-collection-initializers.md @@ -123,6 +123,14 @@ pet.FirstName = "Jane"; Required init-only properties support immutable structures while allowing natural syntax for users of the type. +## Object Initializers with class-typed properties + +When initializing an object, particularly when reusing the current instance, it's crucial to consider the implications for class-typed properties. + +[!code-csharp[ClassTypedInitializer](../../../../samples/snippets/csharp/programming-guide/classes-and-structs/object-collection-initializers/HowToClassTypedInitializer.cs#HowToClassTypedInitializer)] + +The following example shows how, for ClassB, the initialization process involves updating specific values while retaining others from the original instance. The Initializer reuses current instance: ClassB's values will be: `100003` (new value we assign here), `true` (kept from EmbeddedClassTypeA's initialization), `BBBabc` (unchanged default from EmbeddedClassTypeB) + ## Collection initializers Collection initializers let you specify one or more element initializers when you initialize a collection type that implements and has `Add` with the appropriate signature as an instance method or an extension method. The element initializers can be a simple value, an expression, or an object initializer. By using a collection initializer, you do not have to specify multiple calls; the compiler adds the calls automatically. diff --git a/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md b/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md index c835a6f63e6bc..d650dffa2bd94 100644 --- a/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md +++ b/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md @@ -2,7 +2,7 @@ title: "Static Classes and Static Class Members - C# Programming Guide" description: Static classes can't be instantiated in C#. You access the members of a static class by using the class name itself. ms.date: 03/15/2024 -helpviewer_keywords: +helpviewer_keywords: - "C# language, static members" - "static members [C#]" - "static classes [C#]" @@ -12,79 +12,79 @@ ms.assetid: 235614b5-1371-4dbd-9abd-b406a8b0298b --- # Static Classes and Static Class Members (C# Programming Guide) -A [static](../../language-reference/keywords/static.md) class is basically the same as a non-static class, but there's one difference: a static class can't be instantiated. In other words, you can't use the [new](../../language-reference/operators/new-operator.md) operator to create a variable of the class type. Because there's no instance variable, you access the members of a static class by using the class name itself. For example, if you have a static class that is named `UtilityClass` that has a public static method named `MethodA`, you call the method as shown in the following example: - -```csharp -UtilityClass.MethodA(); -``` - - A static class can be used as a convenient container for sets of methods that just operate on input parameters and don't have to get or set any internal instance fields. For example, in the .NET Class Library, the static class contains methods that perform mathematical operations, without any requirement to store or retrieve data that is unique to a particular instance of the class. That is, you apply the members of the class by specifying the class name and the method name, as shown in the following example. - -```csharp -double dub = -3.14; -Console.WriteLine(Math.Abs(dub)); -Console.WriteLine(Math.Floor(dub)); -Console.WriteLine(Math.Round(Math.Abs(dub))); - -// Output: -// 3.14 -// -4 -// 3 -``` - - As is the case with all class types, the .NET runtime loads the type information for a static class when the program that references the class is loaded. The program can't specify exactly when the class is loaded. However, it's guaranteed to load and have its fields initialized and its static constructor called before the class is referenced for the first time in your program. A static constructor is only called one time, and a static class remains in memory for the lifetime of the application domain in which your program resides. - +A [static](../../language-reference/keywords/static.md) class is basically the same as a non-static class, but there's one difference: a static class can't be instantiated. In other words, you can't use the [new](../../language-reference/operators/new-operator.md) operator to create a variable of the class type. Because there's no instance variable, you access the members of a static class by using the class name itself. For example, if you have a static class that is named `UtilityClass` that has a public static method named `MethodA`, you call the method as shown in the following example: + +```csharp +UtilityClass.MethodA(); +``` + + A static class can be used as a convenient container for sets of methods that just operate on input parameters and don't have to get or set any internal instance fields. For example, in the .NET Class Library, the static class contains methods that perform mathematical operations, without any requirement to store or retrieve data that is unique to a particular instance of the class. That is, you apply the members of the class by specifying the class name and the method name, as shown in the following example. + +```csharp +double dub = -3.14; +Console.WriteLine(Math.Abs(dub)); +Console.WriteLine(Math.Floor(dub)); +Console.WriteLine(Math.Round(Math.Abs(dub))); + +// Output: +// 3.14 +// -4 +// 3 +``` + + As is the case with all class types, the .NET runtime loads the type information for a static class when the program that references the class is loaded. The program can't specify exactly when the class is loaded. However, it's guaranteed to load and have its fields initialized and its static constructor called before the class is referenced for the first time in your program. A static constructor is only called one time, and a static class remains in memory for the lifetime of the application domain in which your program resides. + > [!NOTE] -> To create a non-static class that allows only one instance of itself to be created, see [Implementing Singleton in C#](/previous-versions/msp-n-p/ff650316(v=pandp.10)). - - The following list provides the main features of a static class: - -- Contains only static members. - -- Can't be instantiated. - -- Is sealed. - -- Can't contain [Instance Constructors](./instance-constructors.md). - - Creating a static class is therefore basically the same as creating a class that contains only static members and a private constructor. A private constructor prevents the class from being instantiated. The advantage of using a static class is that the compiler can check to make sure that no instance members are accidentally added. The compiler guarantees that instances of this class can't be created. - - Static classes are sealed and therefore can't be inherited. They can't inherit from any class or interface except . Static classes can't contain an instance constructor. However, they can contain a static constructor. Non-static classes should also define a static constructor if the class contains static members that require non-trivial initialization. For more information, see [Static Constructors](./static-constructors.md). - -## Example - - Here's an example of a static class that contains two methods that convert temperature from Celsius to Fahrenheit and from Fahrenheit to Celsius: - - [!code-csharp[TemperatureConverter#1](snippets/static-classes-and-static-class-members/Program.cs#1)] - -## Static Members - - A non-static class can contain static methods, fields, properties, or events. The static member is callable on a class even when no instance of the class exists. The static member is always accessed by the class name, not the instance name. Only one copy of a static member exists, regardless of how many instances of the class are created. Static methods and properties can't access non-static fields and events in their containing type, and they can't access an instance variable of any object unless it's explicitly passed in a method parameter. - - It's more typical to declare a non-static class with some static members, than to declare an entire class as static. Two common uses of static fields are to keep a count of the number of objects that are instantiated, or to store a value that must be shared among all instances. - - Static methods can be overloaded but not overridden, because they belong to the class, and not to any instance of the class. - - Although a field can't be declared as `static const`, a [const](../../language-reference/keywords/const.md) field is essentially static in its behavior. It belongs to the type, not to instances of the type. Therefore, `const` fields can be accessed by using the same `ClassName.MemberName` notation used for static fields. No object instance is required. - - C# doesn't support static local variables (that is, variables that are declared in method scope). - - You declare static class members by using the `static` keyword before the return type of the member, as shown in the following example: - - [!code-csharp[AutomobileExample#2](snippets/static-classes-and-static-class-members/Program.cs#2)] - - Static members are initialized before the static member is accessed for the first time and before the static constructor, if there's one, is called. To access a static class member, use the name of the class instead of a variable name to specify the location of the member, as shown in the following example: - - [!code-csharp[AccessingStaticMembers#3](snippets/static-classes-and-static-class-members/Program.cs#3)] - - If your class contains static fields, provide a static constructor that initializes them when the class is loaded. - - A call to a static method generates a call instruction in Microsoft intermediate language (MSIL), whereas a call to an instance method generates a `callvirt` instruction, which also checks for null object references. However, most of the time the performance difference between the two isn't significant. - -## C# Language Specification +> To create a non-static class that allows only one instance of itself to be created, see [Implementing Singleton in C#](/previous-versions/msp-n-p/ff650316(v=pandp.10)). + + The following list provides the main features of a static class: + +- Contains only static members. + +- Can't be instantiated. + +- Is sealed. + +- Can't contain [Instance Constructors](./instance-constructors.md). + + Creating a static class is therefore basically the same as creating a class that contains only static members and a private constructor. A private constructor prevents the class from being instantiated. The advantage of using a static class is that the compiler can check to make sure that no instance members are accidentally added. The compiler guarantees that instances of this class can't be created. + + Static classes are sealed and therefore can't be inherited. They can't inherit from any class or interface except . Static classes can't contain an instance constructor. However, they can contain a static constructor. Non-static classes should also define a static constructor if the class contains static members that require non-trivial initialization. For more information, see [Static Constructors](./static-constructors.md). + +## Example + + Here's an example of a static class that contains two methods that convert temperature from Celsius to Fahrenheit and from Fahrenheit to Celsius: + + [!code-csharp[TemperatureConverter#1](snippets/static-classes-and-static-class-members/Program.cs#1)] + +## Static Members + + A non-static class can contain static methods, fields, properties, or events. The static member is callable on a class even when no instance of the class exists. The static member is always accessed by the class name, not the instance name. Only one copy of a static member exists, regardless of how many instances of the class are created. Static methods and properties can't access non-static fields and events in their containing type, and they can't access an instance variable of any object unless it's explicitly passed in a method parameter. + + It's more typical to declare a non-static class with some static members, than to declare an entire class as static. Two common uses of static fields are to keep a count of the number of objects that are instantiated, or to store a value that must be shared among all instances. + + Static methods can be overloaded but not overridden, because they belong to the class, and not to any instance of the class. + + Although a field can't be declared as `static const`, a [const](../../language-reference/keywords/const.md) field is essentially static in its behavior. It belongs to the type, not to instances of the type. Therefore, `const` fields can be accessed by using the same `ClassName.MemberName` notation used for static fields. No object instance is required. + + C# doesn't support static local variables (that is, variables that are declared in method scope). + + You declare static class members by using the `static` keyword before the return type of the member, as shown in the following example: + + [!code-csharp[AutomobileExample#2](snippets/static-classes-and-static-class-members/Program.cs#2)] + + Static members are initialized before the static member is accessed for the first time and before the static constructor, if there's one, is called. To access a static class member, use the name of the class instead of a variable name to specify the location of the member, as shown in the following example: + + [!code-csharp[AccessingStaticMembers#3](snippets/static-classes-and-static-class-members/Program.cs#3)] + + If your class contains static fields, provide a static constructor that initializes them when the class is loaded. + + A call to a static method generates a call instruction in common intermediate language (CIL), whereas a call to an instance method generates a `callvirt` instruction, which also checks for null object references. However, most of the time the performance difference between the two isn't significant. + +## C# Language Specification For more information, see [Static classes](~/_csharpstandard/standard/classes.md#15224-static-classes), [Static and instance members](~/_csharpstandard/standard/classes.md#1538-static-and-instance-members) and [Static constructors](~/_csharpstandard/standard/classes.md#1512-static-constructors) in the [C# Language Specification](~/_csharpstandard/standard/README.md). The language specification is the definitive source for C# syntax and usage. - + ## See also - [static](../../language-reference/keywords/static.md) diff --git a/docs/csharp/programming-guide/concepts/index.md b/docs/csharp/programming-guide/concepts/index.md index c06ed69bd96ad..5b0fbde40cd26 100644 --- a/docs/csharp/programming-guide/concepts/index.md +++ b/docs/csharp/programming-guide/concepts/index.md @@ -1,7 +1,7 @@ --- title: "Programming Concepts (C#)" description: Use the resources in this section to understand programming concepts in the C# language, including object-oriented programming. -ms.date: 03/24/2022 +ms.date: 04/22/2024 --- # Programming concepts (C#) @@ -13,10 +13,9 @@ This section explains programming concepts in the C# language. |-------|-------------| |[Covariance and Contravariance (C#)](./covariance-contravariance/index.md)|Shows how to enable implicit conversion of generic type parameters in interfaces and delegates.| |[Iterators (C#)](./iterators.md)|Describes iterators, which are used to step through collections and return elements one at a time.| -|[Language-Integrated Query (LINQ) (C#)](/dotnet/csharp/linq/)|Discusses the powerful query capabilities in the language syntax of C#, and the model for querying relational databases, XML documents, datasets, and in-memory collections.| ## Related sections - [Performance Tips](../../../framework/performance/performance-tips.md) - Discusses several basic rules that may help you increase the performance of your application. + Discusses several basic rules that might help you increase the performance of your application. diff --git a/docs/csharp/programming-guide/concepts/iterators.md b/docs/csharp/programming-guide/concepts/iterators.md index bacdd148a3a13..aedcdc13864ad 100644 --- a/docs/csharp/programming-guide/concepts/iterators.md +++ b/docs/csharp/programming-guide/concepts/iterators.md @@ -329,7 +329,7 @@ In C#, `yield` is not a reserved word and has special meaning only when it is us Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. This class keeps track of the position of the iterator as long the `foreach` loop in the client code continues. -To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that's generated for an iterator method. +To see what the compiler does, you can use the Ildasm.exe tool to view the common intermediate language code that's generated for an iterator method. When you create an iterator for a [class](../../language-reference/keywords/class.md) or [struct](../../language-reference/builtin-types/struct.md), you don't have to implement the whole interface. When the compiler detects the iterator, it automatically generates the `Current`, `MoveNext`, and `Dispose` methods of the or interface. diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md b/docs/csharp/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md deleted file mode 100644 index e7a93a850fefb..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "How to add custom methods for LINQ queries (C#)" -description: Learn how to extend the syntax of LINQ queries by adding extension methods to the IEnumerable interface in C#. -ms.topic: how-to -ms.date: 09/10/2021 -ms.assetid: 1a500f60-2e10-49fb-8b2a-d8d08e4817cb ---- - -# How to add custom methods for LINQ queries (C#) - -You extend the set of methods that you use for LINQ queries by adding extension methods to the interface. For example, in addition to the standard average or maximum operations, you create a custom aggregate method to compute a single value from a sequence of values. You also create a method that works as a custom filter or a specific data transform for a sequence of values and returns a new sequence. Examples of such methods are , , and . - -When you extend the interface, you can apply your custom methods to any enumerable collection. For more information, see [Extension Methods](../../classes-and-structs/extension-methods.md). - -## Add an aggregate method - -An aggregate method computes a single value from a set of values. LINQ provides several aggregate methods, including , , and . You can create your own aggregate method by adding an extension method to the interface. - -The following code example shows how to create an extension method called `Median` to compute a median for a sequence of numbers of type `double`. - -:::code language="csharp" source="./snippets/extensions/LinqExtensions.cs" ID="LinqExtensionClass"::: - -You call this extension method for any enumerable collection in the same way you call other aggregate methods from the interface. - -The following code example shows how to use the `Median` method for an array of type `double`. - -:::code language="csharp" source="./snippets/extensions/Program.cs" ID="MedianUsage"::: - -### Overload an aggregate method to accept various types - -You can overload your aggregate method so that it accepts sequences of various types. The standard approach is to create an overload for each type. Another approach is to create an overload that will take a generic type and convert it to a specific type by using a delegate. You can also combine both approaches. - -#### Create an overload for each type - -You can create a specific overload for each type that you want to support. The following code example shows an overload of the `Median` method for the `int` type. - -:::code language="csharp" source="./snippets/extensions/LinqExtensions.cs" ID="IntOverload"::: - -You can now call the `Median` overloads for both `integer` and `double` types, as shown in the following code: - -:::code language="csharp" source="./snippets/extensions/Program.cs" ID="OverloadUsage"::: - -#### Create a generic overload - -You can also create an overload that accepts a sequence of generic objects. This overload takes a delegate as a parameter and uses it to convert a sequence of objects of a generic type to a specific type. - -The following code shows an overload of the `Median` method that takes the delegate as a parameter. This delegate takes an object of generic type T and returns an object of type `double`. - -:::code language="csharp" source="./snippets/extensions/LinqExtensions.cs" ID="GenericOverload"::: - -You can now call the `Median` method for a sequence of objects of any type. If the type doesn't have its own method overload, you have to pass a delegate parameter. In C#, you can use a lambda expression for this purpose. Also, in Visual Basic only, if you use the `Aggregate` or `Group By` clause instead of the method call, you can pass any value or expression that is in the scope this clause. - -The following example code shows how to call the `Median` method for an array of integers and an array of strings. For strings, the median for the lengths of strings in the array is calculated. The example shows how to pass the delegate parameter to the `Median` method for each case. - -:::code language="csharp" source="./snippets/extensions/Program.cs" ID="GenericUsage"::: - -## Add a method that returns a sequence - -You can extend the interface with a custom query method that returns a sequence of values. In this case, the method must return a collection of type . Such methods can be used to apply filters or data transforms to a sequence of values. - -The following example shows how to create an extension method named `AlternateElements` that returns every other element in a collection, starting from the first element. - -:::code language="csharp" source="./snippets/extensions/LinqExtensions.cs" ID="SequenceElement"::: - -You can call this extension method for any enumerable collection just as you would call other methods from the interface, as shown in the following code: - -:::code language="csharp" source="./snippets/extensions/Program.cs" ID="SequenceUsage"::: - -## See also - -- -- [Extension Methods](../../classes-and-structs/extension-methods.md) diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-combine-and-compare-string-collections-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-combine-and-compare-string-collections-linq.md deleted file mode 100644 index c40c41ce94383..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-combine-and-compare-string-collections-linq.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -title: "How to combine and compare string collections (LINQ) (C#)" -description: This example merges files that contain lines of text. Learn how to do a simple concatenation, a union, and an intersection on the sets of lines in LINQ in C#. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 25926e5b-fde2-4dc1-86a0-16ead7aa13d2 ---- -# How to combine and compare string collections (LINQ) (C#) - -This example shows how to merge files that contain lines of text and then sort the results. Specifically, it shows how to perform a simple concatenation, a union, and an intersection on the two sets of text lines. - -### To set up the project and the text files - -1. Copy these names into a text file that is named names1.txt and save it in your project folder: - - ```text - Bankov, Peter - Holm, Michael - Garcia, Hugo - Potra, Cristina - Noriega, Fabricio - Aw, Kam Foo - Beebe, Ann - Toyoshima, Tim - Guy, Wey Yuan - Garcia, Debra - ``` - -2. Copy these names into a text file that is named names2.txt and save it in your project folder. Note that the two files have some names in common. - - ```text - Liu, Jinghao - Bankov, Peter - Holm, Michael - Garcia, Hugo - Beebe, Ann - Gilchrist, Beth - Myrcha, Jacek - Giakoumakis, Leo - McLin, Nkenge - El Yassir, Mehdi - ``` - -## Example - -```csharp -class MergeStrings - { - static void Main(string[] args) - { - //Put text files in your solution folder - string[] fileA = System.IO.File.ReadAllLines(@"../../../names1.txt"); - string[] fileB = System.IO.File.ReadAllLines(@"../../../names2.txt"); - - //Simple concatenation and sort. Duplicates are preserved. - IEnumerable concatQuery = - fileA.Concat(fileB).OrderBy(s => s); - - // Pass the query variable to another function for execution. - OutputQueryResults(concatQuery, "Simple concatenate and sort. Duplicates are preserved:"); - - // Concatenate and remove duplicate names based on - // default string comparer. - IEnumerable uniqueNamesQuery = - fileA.Union(fileB).OrderBy(s => s); - OutputQueryResults(uniqueNamesQuery, "Union removes duplicate names:"); - - // Find the names that occur in both files (based on - // default string comparer). - IEnumerable commonNamesQuery = - fileA.Intersect(fileB); - OutputQueryResults(commonNamesQuery, "Merge based on intersect:"); - - // Find the matching fields in each list. Merge the two - // results by using Concat, and then - // sort using the default string comparer. - string nameMatch = "Garcia"; - - IEnumerable tempQuery1 = - from name in fileA - let n = name.Split(',') - where n[0] == nameMatch - select name; - - IEnumerable tempQuery2 = - from name2 in fileB - let n2 = name2.Split(',') - where n2[0] == nameMatch - select name2; - - IEnumerable nameMatchQuery = - tempQuery1.Concat(tempQuery2).OrderBy(s => s); - OutputQueryResults(nameMatchQuery, $"Concat based on partial name match \"{nameMatch}\":"); - } - - static void OutputQueryResults(IEnumerable query, string message) - { - Console.WriteLine(System.Environment.NewLine + message); - foreach (string item in query) - { - Console.WriteLine(item); - } - Console.WriteLine("{0} total names in list", query.Count()); - } - } - /* Output: - Simple concatenate and sort. Duplicates are preserved: - Aw, Kam Foo - Bankov, Peter - Bankov, Peter - Beebe, Ann - Beebe, Ann - El Yassir, Mehdi - Garcia, Debra - Garcia, Hugo - Garcia, Hugo - Giakoumakis, Leo - Gilchrist, Beth - Guy, Wey Yuan - Holm, Michael - Holm, Michael - Liu, Jinghao - McLin, Nkenge - Myrcha, Jacek - Noriega, Fabricio - Potra, Cristina - Toyoshima, Tim - 20 total names in list - - Union removes duplicate names: - Aw, Kam Foo - Bankov, Peter - Beebe, Ann - El Yassir, Mehdi - Garcia, Debra - Garcia, Hugo - Giakoumakis, Leo - Gilchrist, Beth - Guy, Wey Yuan - Holm, Michael - Liu, Jinghao - McLin, Nkenge - Myrcha, Jacek - Noriega, Fabricio - Potra, Cristina - Toyoshima, Tim - 16 total names in list - - Merge based on intersect: - Bankov, Peter - Holm, Michael - Garcia, Hugo - Beebe, Ann - 4 total names in list - - Concat based on partial name match "Garcia": - Garcia, Debra - Garcia, Hugo - Garcia, Hugo - 3 total names in list -*/ -``` - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-combine-linq-queries-with-regular-expressions.md b/docs/csharp/programming-guide/concepts/linq/how-to-combine-linq-queries-with-regular-expressions.md deleted file mode 100644 index f2b3a0843353b..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-combine-linq-queries-with-regular-expressions.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "How to combine LINQ queries with regular expressions (C#)" -description: This example creates a regular expression for matching in text strings by using the Regex class in C#. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 6b003b65-20a4-4ca2-929e-2ee3f215aecc ---- -# How to combine LINQ queries with regular expressions (C#) - -This example shows how to use the class to create a regular expression for more complex matching in text strings. The LINQ query makes it easy to filter on exactly the files that you want to search with the regular expression, and to shape the results. - -## Example - -```csharp -class QueryWithRegEx -{ - public static void Main() - { - // Modify this path as necessary so that it accesses your version of Visual Studio. - string startFolder = @"C:\Program Files (x86)\Microsoft Visual Studio 14.0\"; - // One of the following paths may be more appropriate on your computer. - //string startFolder = @"C:\Program Files (x86)\Microsoft Visual Studio\2017\"; - - // Take a snapshot of the file system. - IEnumerable fileList = GetFiles(startFolder); - - // Create the regular expression to find all things "Visual". - System.Text.RegularExpressions.Regex searchTerm = - new System.Text.RegularExpressions.Regex(@"Visual (Basic|C#|C\+\+|Studio)"); - - // Search the contents of each .htm file. - // Remove the where clause to find even more matchedValues! - // This query produces a list of files where a match - // was found, and a list of the matchedValues in that file. - // Note: Explicit typing of "Match" in select clause. - // This is required because MatchCollection is not a - // generic IEnumerable collection. - var queryMatchingFiles = - from file in fileList - where file.Extension == ".htm" - let fileText = System.IO.File.ReadAllText(file.FullName) - let matches = searchTerm.Matches(fileText) - where matches.Count > 0 - select new - { - name = file.FullName, - matchedValues = from System.Text.RegularExpressions.Match match in matches - select match.Value - }; - - // Execute the query. - Console.WriteLine("The term \"{0}\" was found in:", searchTerm.ToString()); - - foreach (var v in queryMatchingFiles) - { - // Trim the path a bit, then write - // the file name in which a match was found. - string s = v.name.Substring(startFolder.Length - 1); - Console.WriteLine(s); - - // For this file, write out all the matching strings - foreach (var v2 in v.matchedValues) - { - Console.WriteLine(" " + v2); - } - } - } - - // This method assumes that the application has discovery - // permissions for all folders under the specified path. - static IEnumerable GetFiles(string path) - { - if (!System.IO.Directory.Exists(path)) - throw new System.IO.DirectoryNotFoundException(); - - string[] fileNames = null; - List files = new List(); - - fileNames = System.IO.Directory.GetFiles(path, "*.*", System.IO.SearchOption.AllDirectories); - foreach (string name in fileNames) - { - files.Add(new System.IO.FileInfo(name)); - } - return files; - } -} -``` - - Note that you can also query the object that is returned by a `RegEx` search. In this example only the value of each match is produced in the results. However, it is also possible to use LINQ to perform all kinds of filtering, sorting, and grouping on that collection. Because is a non-generic collection, you have to explicitly state the type of the range variable in the query. - -## Compiling the Code - - Create a C# console application project with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-compare-the-contents-of-two-folders-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-compare-the-contents-of-two-folders-linq.md deleted file mode 100644 index a917cbf600e9c..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-compare-the-contents-of-two-folders-linq.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: "How to compare the contents of two folders (LINQ) (C#)" -description: This example demonstrates three ways to compare file listings by using LINQ queries in C#. Adapt these techniques to compare sequences of objects of any type. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: c7c4870e-c500-4de3-afa4-2c8e07f510e6 ---- -# How to compare the contents of two folders (LINQ) (C#) - -This example demonstrates three ways to compare two file listings: - -- By querying for a Boolean value that specifies whether the two file lists are identical. - -- By querying for the intersection to retrieve the files that are in both folders. - -- By querying for the set difference to retrieve the files that are in one folder but not the other. - - > [!NOTE] - > The techniques shown here can be adapted to compare sequences of objects of any type. - - The `FileComparer` class shown here demonstrates how to use a custom comparer class together with the Standard Query Operators. The class is not intended for use in real-world scenarios. It just uses the name and length in bytes of each file to determine whether the contents of each folder are identical or not. In a real-world scenario, you should modify this comparer to perform a more rigorous equality check. - -## Example - -```csharp -namespace QueryCompareTwoDirs -{ - class CompareDirs - { - - static void Main(string[] args) - { - - // Create two identical or different temporary folders - // on a local drive and change these file paths. - string pathA = @"C:\TestDir"; - string pathB = @"C:\TestDir2"; - - System.IO.DirectoryInfo dir1 = new System.IO.DirectoryInfo(pathA); - System.IO.DirectoryInfo dir2 = new System.IO.DirectoryInfo(pathB); - - // Take a snapshot of the file system. - IEnumerable list1 = dir1.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - IEnumerable list2 = dir2.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - //A custom file comparer defined below - FileCompare myFileCompare = new FileCompare(); - - // This query determines whether the two folders contain - // identical file lists, based on the custom file comparer - // that is defined in the FileCompare class. - // The query executes immediately because it returns a bool. - bool areIdentical = list1.SequenceEqual(list2, myFileCompare); - - if (areIdentical == true) - { - Console.WriteLine("the two folders are the same"); - } - else - { - Console.WriteLine("The two folders are not the same"); - } - - // Find the common files. It produces a sequence and doesn't - // execute until the foreach statement. - var queryCommonFiles = list1.Intersect(list2, myFileCompare); - - if (queryCommonFiles.Any()) - { - Console.WriteLine("The following files are in both folders:"); - foreach (var v in queryCommonFiles) - { - Console.WriteLine(v.FullName); //shows which items end up in result list - } - } - else - { - Console.WriteLine("There are no common files in the two folders."); - } - - // Find the set difference between the two folders. - // For this example we only check one way. - var queryList1Only = (from file in list1 - select file).Except(list2, myFileCompare); - - Console.WriteLine("The following files are in list1 but not list2:"); - foreach (var v in queryList1Only) - { - Console.WriteLine(v.FullName); - } - } - } - - // This implementation defines a very simple comparison - // between two FileInfo objects. It only compares the name - // of the files being compared and their length in bytes. - class FileCompare : System.Collections.Generic.IEqualityComparer - { - public FileCompare() { } - - public bool Equals(System.IO.FileInfo f1, System.IO.FileInfo f2) - { - return (f1.Name == f2.Name && - f1.Length == f2.Length); - } - - // Return a hash that reflects the comparison criteria. According to the - // rules for IEqualityComparer, if Equals is true, then the hash codes must - // also be equal. Because equality as defined here is a simple value equality, not - // reference identity, it is possible that two or more objects will produce the same - // hash code. - public int GetHashCode(System.IO.FileInfo fi) - { - string s = $"{fi.Name}{fi.Length}"; - return s.GetHashCode(); - } - } -} -``` - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md deleted file mode 100644 index 83d0d423e9d04..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "How to compute column values in a CSV text file (LINQ) (C#)" -description: This example shows how to perform aggregate computations using LINQ in C#, such as Sum, Average, Min, and Max, on the columns of a .csv file. -ms.date: 07/20/2015 -ms.topic: how-to -ms.assetid: 4747f37a-a198-4df2-8efe-5b0731e0ea27 ---- -# How to compute column values in a CSV text file (LINQ) (C#) - -This example shows how to perform aggregate computations such as Sum, Average, Min, and Max on the columns of a .csv file. The example principles that are shown here can be applied to other types of structured text. - -## To create the source file - -1. Copy the following lines into a file that is named scores.csv and save it in your project folder. Assume that the first column represents a student ID, and subsequent columns represent scores from four exams. - - ```csv - 111, 97, 92, 81, 60 - 112, 75, 84, 91, 39 - 113, 88, 94, 65, 91 - 114, 97, 89, 85, 82 - 115, 35, 72, 91, 70 - 116, 99, 86, 90, 94 - 117, 93, 92, 80, 87 - 118, 92, 90, 83, 78 - 119, 68, 79, 88, 92 - 120, 99, 82, 81, 79 - 121, 96, 85, 91, 60 - 122, 94, 92, 91, 91 - ``` - -## Example - -```csharp -class SumColumns -{ - static void Main(string[] args) - { - string[] lines = System.IO.File.ReadAllLines(@"../../../scores.csv"); - - // Specifies the column to compute. - int exam = 3; - - // Spreadsheet format: - // Student ID Exam#1 Exam#2 Exam#3 Exam#4 - // 111, 97, 92, 81, 60 - - // Add one to exam to skip over the first column, - // which holds the student ID. - SingleColumn(lines, exam + 1); - Console.WriteLine(); - MultiColumns(lines); - - Console.WriteLine("Press any key to exit"); - Console.ReadKey(); - } - - static void SingleColumn(IEnumerable strs, int examNum) - { - Console.WriteLine("Single Column Query:"); - - // Parameter examNum specifies the column to - // run the calculations on. This value could be - // passed in dynamically at run time. - - // Variable columnQuery is an IEnumerable. - // The following query performs two steps: - // 1) use Split to break each row (a string) into an array - // of strings, - // 2) convert the element at position examNum to an int - // and select it. - var columnQuery = - from line in strs - let elements = line.Split(',') - select Convert.ToInt32(elements[examNum]); - - // Execute the query and cache the results to improve - // performance. This is helpful only with very large files. - var results = columnQuery.ToList(); - - // Perform aggregate calculations Average, Max, and - // Min on the column specified by examNum. - double average = results.Average(); - int max = results.Max(); - int min = results.Min(); - - Console.WriteLine("Exam #{0}: Average:{1:##.##} High Score:{2} Low Score:{3}", - examNum, average, max, min); - } - - static void MultiColumns(IEnumerable strs) - { - Console.WriteLine("Multi Column Query:"); - - // Create a query, multiColQuery. Explicit typing is used - // to make clear that, when executed, multiColQuery produces - // nested sequences. However, you get the same results by - // using 'var'. - - // The multiColQuery query performs the following steps: - // 1) use Split to break each row (a string) into an array - // of strings, - // 2) use Skip to skip the "Student ID" column, and store the - // rest of the row in scores. - // 3) convert each score in the current row from a string to - // an int, and select that entire sequence as one row - // in the results. - IEnumerable> multiColQuery = - from line in strs - let elements = line.Split(',') - let scores = elements.Skip(1) - select (from str in scores - select Convert.ToInt32(str)); - - // Execute the query and cache the results to improve - // performance. - // ToArray could be used instead of ToList. - var results = multiColQuery.ToList(); - - // Find out how many columns you have in results. - int columnCount = results[0].Count(); - - // Perform aggregate calculations Average, Max, and - // Min on each column. - // Perform one iteration of the loop for each column - // of scores. - // You can use a for loop instead of a foreach loop - // because you already executed the multiColQuery - // query by calling ToList. - for (int column = 0; column < columnCount; column++) - { - var results2 = from row in results - select row.ElementAt(column); - double average = results2.Average(); - int max = results2.Max(); - int min = results2.Min(); - - // Add one to column because the first exam is Exam #1, - // not Exam #0. - Console.WriteLine("Exam #{0} Average: {1:##.##} High Score: {2} Low Score: {3}", - column + 1, average, max, min); - } - } -} -/* Output: - Single Column Query: - Exam #4: Average:76.92 High Score:94 Low Score:39 - - Multi Column Query: - Exam #1 Average: 86.08 High Score: 99 Low Score: 35 - Exam #2 Average: 86.42 High Score: 94 Low Score: 72 - Exam #3 Average: 84.75 High Score: 91 Low Score: 65 - Exam #4 Average: 76.92 High Score: 94 Low Score: 39 - */ -``` - - The query works by using the method to convert each line of text into an array. Each array element represents a column. Finally, the text in each column is converted to its numeric representation. If your file is a tab-separated file, just update the argument in the `Split` method to `\t`. - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md deleted file mode 100644 index a362a4c72b84a..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "How to count occurrences of a word in a string (LINQ) (C#)" -description: This example uses a LINQ query in C# to count the occurrences of a specified word in a string. It uses the Split method to create an array of words. -ms.date: 07/20/2015 -ms.topic: how-to -ms.assetid: f8e6f546-7c14-4aa1-8a75-e8d09f3b8ccd ---- -# How to count occurrences of a word in a string (LINQ) (C#) - -This example shows how to use a LINQ query to count the occurrences of a specified word in a string. Note that to perform the count, first the method is called to create an array of words. There is a performance cost to the method. If the only operation on the string is to count the words, you should consider using the or methods instead. However, if performance is not a critical issue, or you have already split the sentence in order to perform other types of queries over it, then it makes sense to use LINQ to count the words or phrases as well. - -## Example - -```csharp -class CountWords -{ - static void Main() - { - string text = @"Historically, the world of data and the world of objects" + - @" have not been well integrated. Programmers work in C# or Visual Basic" + - @" and also in SQL or XQuery. On the one side are concepts such as classes," + - @" objects, fields, inheritance, and .NET APIs. On the other side" + - @" are tables, columns, rows, nodes, and separate languages for dealing with" + - @" them. Data types often require translation between the two worlds; there are" + - @" different standard functions. Because the object world has no notion of query, a" + - @" query can only be represented as a string without compile-time type checking or" + - @" IntelliSense support in the IDE. Transferring data from SQL tables or XML trees to" + - @" objects in memory is often tedious and error-prone."; - - string searchTerm = "data"; - - //Convert the string into an array of words - string[] source = text.Split( - ['.', '?', '!', ' ', ';', ':', ','], - StringSplitOptions.RemoveEmptyEntries); - - // Create the query. Use the InvariantCultureIgnoreCase comparison to match "data" and "Data" - var matchQuery = from word in source - where word.Equals(searchTerm, StringComparison.InvariantCultureIgnoreCase) - select word; - - // Count the matches, which executes the query. - int wordCount = matchQuery.Count(); - Console.WriteLine("{0} occurrences(s) of the search term \"{1}\" were found.", wordCount, searchTerm); - } -} -/* Output: - 3 occurrences(s) of the search term "data" were found. -*/ -``` - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md deleted file mode 100644 index a791a209d95c1..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "How to find the set difference between two lists (LINQ) (C#)" -description: Learn how to use LINQ in C# to compare two lists of strings and output those lines that are in one list but not in the other. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 8e8945f0-4aba-439d-8d5d-c8d1eeef4e71 ---- -# How to find the set difference between two lists (LINQ) (C#) - -This example shows how to use LINQ to compare two lists of strings and output those lines that are in names1.txt but not in names2.txt. - -### To create the data files - -1. Copy names1.txt and names2.txt to your solution folder as shown in [How to combine and compare string collections (LINQ) (C#)](./how-to-combine-and-compare-string-collections-linq.md). - -## Example - -```csharp -class CompareLists -{ - static void Main() - { - // Create the IEnumerable data sources. - string[] names1 = System.IO.File.ReadAllLines(@"../../../names1.txt"); - string[] names2 = System.IO.File.ReadAllLines(@"../../../names2.txt"); - - // Create the query. Note that method syntax must be used here. - IEnumerable differenceQuery = - names1.Except(names2); - - // Execute the query. - Console.WriteLine("The following lines are in names1.txt but not names2.txt"); - foreach (string s in differenceQuery) - Console.WriteLine(s); - - // Keep the console window open until the user presses a key. - Console.WriteLine("Press any key to exit"); - Console.ReadKey(); - } -} -/* Output: - The following lines are in names1.txt but not names2.txt - Potra, Cristina - Noriega, Fabricio - Aw, Kam Foo - Toyoshima, Tim - Guy, Wey Yuan - Garcia, Debra - */ -``` - - Some types of query operations in C#, such as , , , and , can only be expressed in method-based syntax. - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md deleted file mode 100644 index 743d2ed005bad..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: "How to group files by extension (LINQ) (C#)" -description: Learn how to use LINQ to do advanced grouping and sorting operations on lists of files or folders in C#. The example shows how to page output in the console. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 21a98320-a5a1-4981-82d8-6a637e7d9018 ---- -# How to group files by extension (LINQ) (C#) - -This example shows how LINQ can be used to perform advanced grouping and sorting operations on lists of files or folders. It also shows how to page output in the console window by using the and methods. - -## Example - - The following query shows how to group the contents of a specified directory tree by the file name extension. - -```csharp -class GroupByExtension -{ - // This query will sort all the files under the specified folder - // and subfolder into groups keyed by the file extension. - private static void Main() - { - // Take a snapshot of the file system. - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\Common7"; - - // Used in WriteLine to trim output lines. - int trimLength = startFolder.Length; - - // Take a snapshot of the file system. - System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(startFolder); - - // This method assumes that the application has discovery permissions - // for all folders under the specified path. - IEnumerable fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - // Create the query. - var queryGroupByExt = - from file in fileList - group file by file.Extension.ToLower() into fileGroup - orderby fileGroup.Key - select fileGroup; - - // Display one group at a time. If the number of - // entries is greater than the number of lines - // in the console window, then page the output. - PageOutput(trimLength, queryGroupByExt); - } - - // This method specifically handles group queries of FileInfo objects with string keys. - // It can be modified to work for any long listings of data. Note that explicit typing - // must be used in method signatures. The groupbyExtList parameter is a query that produces - // groups of FileInfo objects with string keys. - private static void PageOutput(int rootLength, - IEnumerable> groupByExtList) - { - // Flag to break out of paging loop. - bool goAgain = true; - - // "3" = 1 line for extension + 1 for "Press any key" + 1 for input cursor. - int numLines = Console.WindowHeight - 3; - - // Iterate through the outer collection of groups. - foreach (var filegroup in groupByExtList) - { - // Start a new extension at the top of a page. - int currentLine = 0; - - // Output only as many lines of the current group as will fit in the window. - do - { - Console.Clear(); - Console.WriteLine(filegroup.Key == String.Empty ? "[none]" : filegroup.Key); - - // Get 'numLines' number of items starting at number 'currentLine'. - var resultPage = filegroup.Skip(currentLine).Take(numLines); - - //Execute the resultPage query - foreach (var f in resultPage) - { - Console.WriteLine("\t{0}", f.FullName.Substring(rootLength)); - } - - // Increment the line counter. - currentLine += numLines; - - // Give the user a chance to escape. - Console.WriteLine("Press any key to continue or the 'End' key to break..."); - ConsoleKey key = Console.ReadKey().Key; - if (key == ConsoleKey.End) - { - goAgain = false; - break; - } - } while (currentLine < filegroup.Count()); - - if (goAgain == false) - break; - } - } -} -``` - - The output from this program can be long, depending on the details of the local file system and what the `startFolder` is set to. To enable viewing of all results, this example shows how to page through results. The same techniques can be applied to Windows and Web applications. Notice that because the code pages the items in a group, a nested `foreach` loop is required. There is also some additional logic to compute the current position in the list, and to enable the user to stop paging and exit the program. In this particular case, the paging query is run against the cached results from the original query. In other contexts, such as LINQ to SQL, such caching is not required. - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-join-content-from-dissimilar-files-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-join-content-from-dissimilar-files-linq.md deleted file mode 100644 index 3f6bb942809c9..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-join-content-from-dissimilar-files-linq.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: "How to join content from dissimilar files (LINQ) (C#)" -description: Learn how to join data from two comma-delimited files by using LINQ in C#. The data shares a common value that is used as a matching key. -ms.date: 06/27/2018 -ms.topic: how-to -ms.assetid: aa2d12a6-70a9-492f-a6db-b2b850d46811 ---- -# How to join content from dissimilar files (LINQ) (C#) - -This example shows how to join data from two comma-delimited files that share a common value that is used as a matching key. This technique can be useful if you have to combine data from two spreadsheets, or from a spreadsheet and from a file that has another format, into a new file. You can modify the example to work with any kind of structured text. - -## To create the data files - -1. Copy the following lines into a file that is named *scores.csv* and save it to your project folder. The file represents spreadsheet data. Column 1 is the student's ID, and columns 2 through 5 are test scores. - - ```csv - 111, 97, 92, 81, 60 - 112, 75, 84, 91, 39 - 113, 88, 94, 65, 91 - 114, 97, 89, 85, 82 - 115, 35, 72, 91, 70 - 116, 99, 86, 90, 94 - 117, 93, 92, 80, 87 - 118, 92, 90, 83, 78 - 119, 68, 79, 88, 92 - 120, 99, 82, 81, 79 - 121, 96, 85, 91, 60 - 122, 94, 92, 91, 91 - ``` - -2. Copy the following lines into a file that is named *names.csv* and save it to your project folder. The file represents a spreadsheet that contains the student's last name, first name, and student ID. - - ```csv - Omelchenko,Svetlana,111 - O'Donnell,Claire,112 - Mortensen,Sven,113 - Garcia,Cesar,114 - Garcia,Debra,115 - Fakhouri,Fadi,116 - Feng,Hanying,117 - Garcia,Hugo,118 - Tucker,Lance,119 - Adams,Terry,120 - Zabokritski,Eugene,121 - Tucker,Michael,122 - ``` - -## Example - -```csharp -using System; -using System.Collections.Generic; -using System.Linq; - -class JoinStrings -{ - static void Main() - { - // Join content from dissimilar files that contain - // related information. File names.csv contains the student - // name plus an ID number. File scores.csv contains the ID - // and a set of four test scores. The following query joins - // the scores to the student names by using ID as a - // matching key. - - string[] names = System.IO.File.ReadAllLines(@"../../../names.csv"); - string[] scores = System.IO.File.ReadAllLines(@"../../../scores.csv"); - - // Name: Last[0], First[1], ID[2] - // Omelchenko, Svetlana, 11 - // Score: StudentID[0], Exam1[1] Exam2[2], Exam3[3], Exam4[4] - // 111, 97, 92, 81, 60 - - // This query joins two dissimilar spreadsheets based on common ID value. - // Multiple from clauses are used instead of a join clause - // in order to store results of id.Split. - IEnumerable scoreQuery1 = - from name in names - let nameFields = name.Split(',') - from id in scores - let scoreFields = id.Split(',') - where Convert.ToInt32(nameFields[2]) == Convert.ToInt32(scoreFields[0]) - select nameFields[0] + "," + scoreFields[1] + "," + scoreFields[2] - + "," + scoreFields[3] + "," + scoreFields[4]; - - // Pass a query variable to a method and execute it - // in the method. The query itself is unchanged. - OutputQueryResults(scoreQuery1, "Merge two spreadsheets:"); - - // Keep console window open in debug mode. - Console.WriteLine("Press any key to exit"); - Console.ReadKey(); - } - - static void OutputQueryResults(IEnumerable query, string message) - { - Console.WriteLine(System.Environment.NewLine + message); - foreach (string item in query) - { - Console.WriteLine(item); - } - Console.WriteLine("{0} total names in list", query.Count()); - } -} -/* Output: -Merge two spreadsheets: -Omelchenko, 97, 92, 81, 60 -O'Donnell, 75, 84, 91, 39 -Mortensen, 88, 94, 65, 91 -Garcia, 97, 89, 85, 82 -Garcia, 35, 72, 91, 70 -Fakhouri, 99, 86, 90, 94 -Feng, 93, 92, 80, 87 -Garcia, 92, 90, 83, 78 -Tucker, 68, 79, 88, 92 -Adams, 99, 82, 81, 79 -Zabokritski, 96, 85, 91, 60 -Tucker, 94, 92, 91, 91 -12 total names in list - */ -``` diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md deleted file mode 100644 index 06ca6616fa73e..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "How to populate object collections from multiple sources (LINQ) (C#)" -description: Learn how to merge data from different sources into a sequence of new types by using LINQ in C#. These examples use both anonymous and named types. -ms.topic: how-to -ms.date: 06/12/2018 -ms.assetid: 8ad7d480-b46c-4ccc-8c57-76f2d04ccc6d ---- -# How to populate object collections from multiple sources (LINQ) (C#) - -This example shows how to merge data from different sources into a sequence of new types. - -> [!NOTE] -> Don't try to join in-memory data or data in the file system with data that is still in a database. Such cross-domain joins can yield undefined results because of different ways in which join operations might be defined for database queries and other types of sources. Additionally, there is a risk that such an operation could cause an out-of-memory exception if the amount of data in the database is large enough. To join data from a database to in-memory data, first call `ToList` or `ToArray` on the database query, and then perform the join on the returned collection. - -## To create the data file - -Copy the names.csv and scores.csv files into your project folder, as described in [How to join content from dissimilar files (LINQ) (C#)](./how-to-join-content-from-dissimilar-files-linq.md). - -## Example - -The following example shows how to use a named type `Student` to store merged data from two in-memory collections of strings that simulate spreadsheet data in .csv format. The first collection of strings represents the student names and IDs, and the second collection represents the student ID (in the first column) and four exam scores. The ID is used as the foreign key. - -```csharp -using System; -using System.Collections.Generic; -using System.Linq; - -class Student -{ - public string FirstName { get; set; } - public string LastName { get; set; } - public int ID { get; set; } - public List ExamScores { get; set; } -} - -class PopulateCollection -{ - static void Main() - { - // These data files are defined in How to join content from - // dissimilar files (LINQ). - - // Each line of names.csv consists of a last name, a first name, and an - // ID number, separated by commas. For example, Omelchenko,Svetlana,111 - string[] names = System.IO.File.ReadAllLines(@"../../../names.csv"); - - // Each line of scores.csv consists of an ID number and four test - // scores, separated by commas. For example, 111, 97, 92, 81, 60 - string[] scores = System.IO.File.ReadAllLines(@"../../../scores.csv"); - - // Merge the data sources using a named type. - // var could be used instead of an explicit type. Note the dynamic - // creation of a list of ints for the ExamScores member. The first item - // is skipped in the split string because it is the student ID, - // not an exam score. - IEnumerable queryNamesScores = - from nameLine in names - let splitName = nameLine.Split(',') - from scoreLine in scores - let splitScoreLine = scoreLine.Split(',') - where Convert.ToInt32(splitName[2]) == Convert.ToInt32(splitScoreLine[0]) - select new Student() - { - FirstName = splitName[0], - LastName = splitName[1], - ID = Convert.ToInt32(splitName[2]), - ExamScores = (from scoreAsText in splitScoreLine.Skip(1) - select Convert.ToInt32(scoreAsText)). - ToList() - }; - - // Optional. Store the newly created student objects in memory - // for faster access in future queries. This could be useful with - // very large data files. - List students = queryNamesScores.ToList(); - - // Display each student's name and exam score average. - foreach (var student in students) - { - Console.WriteLine("The average score of {0} {1} is {2}.", - student.FirstName, student.LastName, - student.ExamScores.Average()); - } - - //Keep console window open in debug mode - Console.WriteLine("Press any key to exit."); - Console.ReadKey(); - } -} -/* Output: - The average score of Omelchenko Svetlana is 82.5. - The average score of O'Donnell Claire is 72.25. - The average score of Mortensen Sven is 84.5. - The average score of Garcia Cesar is 88.25. - The average score of Garcia Debra is 67. - The average score of Fakhouri Fadi is 92.25. - The average score of Feng Hanying is 88. - The average score of Garcia Hugo is 85.75. - The average score of Tucker Lance is 81.75. - The average score of Adams Terry is 85.25. - The average score of Zabokritski Eugene is 83. - The average score of Tucker Michael is 92. - */ -``` - -In the [select](../../../language-reference/keywords/select-clause.md) clause, an object initializer is used to instantiate each new `Student` object by using the data from the two sources. - -If you don't have to store the results of a query, anonymous types can be more convenient than named types. Named types are required if you pass the query results outside the method in which the query is executed. The following example executes the same task as the previous example, but uses anonymous types instead of named types: - -```csharp -// Merge the data sources by using an anonymous type. -// Note the dynamic creation of a list of ints for the -// ExamScores member. We skip 1 because the first string -// in the array is the student ID, not an exam score. -var queryNamesScores2 = - from nameLine in names - let splitName = nameLine.Split(',') - from scoreLine in scores - let splitScoreLine = scoreLine.Split(',') - where Convert.ToInt32(splitName[2]) == Convert.ToInt32(splitScoreLine[0]) - select new - { - First = splitName[0], - Last = splitName[1], - ExamScores = (from scoreAsText in splitScoreLine.Skip(1) - select Convert.ToInt32(scoreAsText)) - .ToList() - }; - -// Display each student's name and exam score average. -foreach (var student in queryNamesScores2) -{ - Console.WriteLine("The average score of {0} {1} is {2}.", - student.First, student.Last, student.ExamScores.Average()); -} -``` - -## See also - -- [Object and Collection Initializers](../../classes-and-structs/object-and-collection-initializers.md) -- [Anonymous Types](../../../fundamentals/types/anonymous-types.md) diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md deleted file mode 100644 index 861ed35261ff9..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "How to query an ArrayList with LINQ (C#)" -description: This example uses LINQ to query over an ArrayList in C#. You must declare the type of the range variable to reflect the type of the objects in the collection. -ms.date: 07/20/2015 -ms.topic: how-to -ms.assetid: 2bfb471c-6e9a-4e60-bd83-4a1778abde11 ---- -# How to query an ArrayList with LINQ (C#) - -When using LINQ to query non-generic collections such as , you must explicitly declare the type of the range variable to reflect the specific type of the objects in the collection. For example, if you have an of `Student` objects, your [from clause](../../../language-reference/keywords/from-clause.md) should look like this: - -```csharp -var query = from Student s in arrList -//... -``` - - By specifying the type of the range variable, you are casting each item in the to a `Student`. - - The use of an explicitly typed range variable in a query expression is equivalent to calling the method. throws an exception if the specified cast cannot be performed. and are the two Standard Query Operator methods that operate on non-generic types. For more information, see [Type Relationships in LINQ Query Operations](../../../linq/get-started/type-relationships-in-linq-query-operations.md). - -## Example - - The following example shows a simple query over an . Note that this example uses object initializers when the code calls the method, but this is not a requirement. - -```csharp -using System; -using System.Collections; -using System.Linq; - -namespace NonGenericLINQ -{ - public class Student - { - public string FirstName { get; set; } - public string LastName { get; set; } - public int[] Scores { get; set; } - } - - class Program - { - static void Main(string[] args) - { - ArrayList arrList = new ArrayList(); - arrList.Add( - new Student - { - FirstName = "Svetlana", LastName = "Omelchenko", Scores = new int[] { 98, 92, 81, 60 } - }); - arrList.Add( - new Student - { - FirstName = "Claire", LastName = "O’Donnell", Scores = new int[] { 75, 84, 91, 39 } - }); - arrList.Add( - new Student - { - FirstName = "Sven", LastName = "Mortensen", Scores = new int[] { 88, 94, 65, 91 } - }); - arrList.Add( - new Student - { - FirstName = "Cesar", LastName = "Garcia", Scores = new int[] { 97, 89, 85, 82 } - }); - - var query = from Student student in arrList - where student.Scores[0] > 95 - select student; - - foreach (Student s in query) - Console.WriteLine(s.LastName + ": " + s.Scores[0]); - } - } -} -/* Output: - Omelchenko: 98 - Garcia: 97 -*/ -``` - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md deleted file mode 100644 index 58afcc568e0b9..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "How to query for characters in a string (LINQ) (C#)" -description: You can query a string as a sequence of characters in LINQ. This C# example queries a string to determine the number of numeric digits it contains. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 727a1be7-dbec-4ab8-b414-bc2d56feb6ff ---- -# How to query for characters in a string (LINQ) (C#) - -Because the class implements the generic interface, any string can be queried as a sequence of characters. However, this is not a common use of LINQ. For complex pattern matching operations, use the class. - -## Example - - The following example queries a string to determine the number of numeric digits it contains. Note that the query is "reused" after it is executed the first time. This is possible because the query itself does not store any actual results. - -```csharp -class QueryAString -{ - static void Main() - { - string aString = "ABCDE99F-J74-12-89A"; - - // Select only those characters that are numbers - IEnumerable stringQuery = - from ch in aString - where Char.IsDigit(ch) - select ch; - - // Execute the query - foreach (char c in stringQuery) - Console.Write(c + " "); - - // Call the Count method on the existing query. - int count = stringQuery.Count(); - Console.WriteLine("Count = {0}", count); - - // Select all characters before the first '-' - IEnumerable stringQuery2 = aString.TakeWhile(c => c != '-'); - - // Execute the second query - foreach (char c in stringQuery2) - Console.Write(c); - - Console.WriteLine(System.Environment.NewLine + "Press any key to exit"); - Console.ReadKey(); - } -} -/* Output: - Output: 9 9 7 4 1 2 8 9 - Count = 8 - ABCDE99F -*/ -``` - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - -## See also - -- [How to combine LINQ queries with regular expressions (C#)](./how-to-combine-linq-queries-with-regular-expressions.md) diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-duplicate-files-in-a-directory-tree-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-for-duplicate-files-in-a-directory-tree-linq.md deleted file mode 100644 index f2b17a46530ef..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-duplicate-files-in-a-directory-tree-linq.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: "How to query for duplicate files in a directory tree (LINQ) (C#)" -description: Learn how to use LINQ in C# to query for duplicate file names in different directories and how to query for files whose size and LastWrite times also match. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 1ff5562b-0d30-46d1-b426-a04e8f78c840 ---- -# How to query for duplicate files in a directory tree (LINQ) (C#) - -Sometimes files that have the same name may be located in more than one folder. For example, under the Visual Studio installation folder, several folders have a readme.htm file. This example shows how to query for such duplicate file names under a specified root folder. The second example shows how to query for files whose size and LastWrite times also match. - -## Example - -```csharp -class QueryDuplicateFileNames -{ - static void Main(string[] args) - { - // Uncomment QueryDuplicates2 to run that query. - QueryDuplicates(); - // QueryDuplicates2(); - } - - static void QueryDuplicates() - { - // Change the root drive or folder if necessary - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\"; - - // Take a snapshot of the file system. - System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(startFolder); - - // This method assumes that the application has discovery permissions - // for all folders under the specified path. - IEnumerable fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - // used in WriteLine to keep the lines shorter - int charsToSkip = startFolder.Length; - - // var can be used for convenience with groups. - var queryDupNames = - from file in fileList - group file.FullName.Substring(charsToSkip) by file.Name into fileGroup - where fileGroup.Count() > 1 - select fileGroup; - - // Pass the query to a method that will - // output one page at a time. - PageOutput(queryDupNames); - } - - // A Group key that can be passed to a separate method. - // Override Equals and GetHashCode to define equality for the key. - // Override ToString to provide a friendly name for Key.ToString() - class PortableKey - { - public string Name { get; set; } - public DateTime LastWriteTime { get; set; } - public long Length { get; set; } - - public override bool Equals(object obj) - { - PortableKey other = (PortableKey)obj; - return other.LastWriteTime == this.LastWriteTime && - other.Length == this.Length && - other.Name == this.Name; - } - - public override int GetHashCode() - { - string str = $"{this.LastWriteTime}{this.Length}{this.Name}"; - return str.GetHashCode(); - } - public override string ToString() - { - return $"{this.Name} {this.Length} {this.LastWriteTime}"; - } - } - static void QueryDuplicates2() - { - // Change the root drive or folder if necessary. - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\Common7"; - - // Make the lines shorter for the console display - int charsToSkip = startFolder.Length; - - // Take a snapshot of the file system. - System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(startFolder); - IEnumerable fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - // Note the use of a compound key. Files that match - // all three properties belong to the same group. - // A named type is used to enable the query to be - // passed to another method. Anonymous types can also be used - // for composite keys but cannot be passed across method boundaries - // - var queryDupFiles = - from file in fileList - group file.FullName.Substring(charsToSkip) by - new PortableKey { Name = file.Name, LastWriteTime = file.LastWriteTime, Length = file.Length } into fileGroup - where fileGroup.Count() > 1 - select fileGroup; - - var list = queryDupFiles.ToList(); - - int i = queryDupFiles.Count(); - - PageOutput(queryDupFiles); - } - - // A generic method to page the output of the QueryDuplications methods - // Here the type of the group must be specified explicitly. "var" cannot - // be used in method signatures. This method does not display more than one - // group per page. - private static void PageOutput(IEnumerable> groupByExtList) - { - // Flag to break out of paging loop. - bool goAgain = true; - - // "3" = 1 line for extension + 1 for "Press any key" + 1 for input cursor. - int numLines = Console.WindowHeight - 3; - - // Iterate through the outer collection of groups. - foreach (var filegroup in groupByExtList) - { - // Start a new extension at the top of a page. - int currentLine = 0; - - // Output only as many lines of the current group as will fit in the window. - do - { - Console.Clear(); - Console.WriteLine("Filename = {0}", filegroup.Key.ToString() == String.Empty ? "[none]" : filegroup.Key.ToString()); - - // Get 'numLines' number of items starting at number 'currentLine'. - var resultPage = filegroup.Skip(currentLine).Take(numLines); - - //Execute the resultPage query - foreach (var fileName in resultPage) - { - Console.WriteLine("\t{0}", fileName); - } - - // Increment the line counter. - currentLine += numLines; - - // Give the user a chance to escape. - Console.WriteLine("Press any key to continue or the 'End' key to break..."); - ConsoleKey key = Console.ReadKey().Key; - if (key == ConsoleKey.End) - { - goAgain = false; - break; - } - } while (currentLine < filegroup.Count()); - - if (goAgain == false) - break; - } - } -} -``` - - The first query uses a simple key to determine a match; this finds files that have the same name but whose contents might be different. The second query uses a compound key to match against three properties of the object. This query is much more likely to find files that have the same name and similar or identical content. - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-files-with-a-specified-attribute-or-name.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-for-files-with-a-specified-attribute-or-name.md deleted file mode 100644 index 1f3733e6b0785..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-files-with-a-specified-attribute-or-name.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "How to query for files with a specified attribute or name (C#)" -description: Learn how to use LINQ in C# to find files that have a specified file name extension in a directory tree and how to return either the newest or oldest file. -ms.date: 07/20/2015 -ms.topic: how-to -ms.assetid: 560e3879-b0b3-4549-ad02-0a53aff2f83c ---- -# How to query for files with a specified attribute or name (C#) - -This example shows how to find all files that have a specified file name extension (for example ".txt") in a specified directory tree. It also shows how to return either the newest or oldest file in the tree based on the creation time. - -## Example - -```csharp -class FindFileByExtension -{ - // This query will produce the full path for all .txt files - // under the specified folder including subfolders. - // It orders the list according to the file name. - static void Main() - { - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\"; - - // Take a snapshot of the file system. - System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(startFolder); - - // This method assumes that the application has discovery permissions - // for all folders under the specified path. - IEnumerable fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - //Create the query - IEnumerable fileQuery = - from file in fileList - where file.Extension == ".txt" - orderby file.Name - select file; - - //Execute the query. This might write out a lot of files! - foreach (System.IO.FileInfo fi in fileQuery) - { - Console.WriteLine(fi.FullName); - } - - // Create and execute a new query by using the previous - // query as a starting point. fileQuery is not - // executed again until the call to Last() - var newestFile = - (from file in fileQuery - orderby file.CreationTime - select new { file.FullName, file.CreationTime }) - .Last(); - - Console.WriteLine("\r\nThe newest .txt file is {0}. Creation time: {1}", - newestFile.FullName, newestFile.CreationTime); - } -} -``` - -## Compiling the Code - - Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words-linq.md deleted file mode 100644 index d94a27df87abd..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words-linq.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "How to query for sentences that contain a specified set of words (LINQ) (C#)" -description: Learn how to use LINQ in C# to find sentences in a text file that contain matches for each of a set of words, which could be populated at run time. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 0724b429-4b87-4d26-a7b1-409358f3fc20 ---- -# How to query for sentences that contain a specified set of words (LINQ) (C#) - -This example shows how to find sentences in a text file that contain matches for each of a specified set of words. Although the array of search terms is hard-coded in this example, it could also be populated dynamically at run time. In this example, the query returns the sentences that contain the words "Historically," "data," and "integrated." - -## Example - -```csharp -class FindSentences -{ - static void Main() - { - string text = @"Historically, the world of data and the world of objects " + - @"have not been well integrated. Programmers work in C# or Visual Basic " + - @"and also in SQL or XQuery. On the one side are concepts such as classes, " + - @"objects, fields, inheritance, and .NET APIs. On the other side " + - @"are tables, columns, rows, nodes, and separate languages for dealing with " + - @"them. Data types often require translation between the two worlds; there are " + - @"different standard functions. Because the object world has no notion of query, a " + - @"query can only be represented as a string without compile-time type checking or " + - @"IntelliSense support in the IDE. Transferring data from SQL tables or XML trees to " + - @"objects in memory is often tedious and error-prone."; - - // Split the text block into an array of sentences. - string[] sentences = text.Split(['.', '?', '!' ]); - - // Define the search terms. This list could also be dynamically populated at run time. - string[] wordsToMatch = { "Historically", "data", "integrated" }; - - // Find sentences that contain all the terms in the wordsToMatch array. - // Note that the number of terms to match is not specified at compile time. - var sentenceQuery = from sentence in sentences - let w = sentence.Split(['.', '?', '!', ' ', ';', ':', ','], - StringSplitOptions.RemoveEmptyEntries) - where w.Distinct().Intersect(wordsToMatch).Count() == wordsToMatch.Count() - select sentence; - - // Execute the query. Note that you can explicitly type - // the iteration variable here even though sentenceQuery - // was implicitly typed. - foreach (string str in sentenceQuery) - { - Console.WriteLine(str); - } - } -} -/* Output: -Historically, the world of data and the world of objects have not been well integrated -*/ -``` - - The query works by first splitting the text into sentences, and then splitting the sentences into an array of strings that hold each word. For each of these arrays, the method removes all duplicate words, and then the query performs an operation on the word array and the `wordsToMatch` array. If the count of the intersection is the same as the count of the `wordsToMatch` array, all words were found in the words and the original sentence is returned. - - In the call to , the punctuation marks are used as separators in order to remove them from the string. If you did not do this, for example you could have a string "Historically," that would not match "Historically" in the `wordsToMatch` array. You may have to use additional separators, depending on the types of punctuation found in the source text. - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree-linq.md deleted file mode 100644 index 0397d139e4801..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree-linq.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: "How to query for the largest file or files in a directory tree (LINQ) (C#)" -description: This C# example shows five LINQ queries related to file size in bytes. You can modify these to query on some other property of the FileInfo object. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 20c8a917-0552-4514-b489-0b8b6a4c3b4c ---- -# How to query for the largest file or files in a directory tree (LINQ) (C#) - -This example shows five queries related to file size in bytes: - -- How to retrieve the size in bytes of the largest file. - -- How to retrieve the size in bytes of the smallest file. - -- How to retrieve the object largest or smallest file from one or more folders under a specified root folder. - -- How to retrieve a sequence such as the 10 largest files. - -- How to order files into groups based on their file size in bytes, ignoring files that are less than a specified size. - -## Example - - The following example contains five separate queries that show how to query and group files, depending on their file size in bytes. You can easily modify these examples to base the query on some other property of the object. - -```csharp -class QueryBySize -{ - static void Main(string[] args) - { - QueryFilesBySize(); - Console.WriteLine("Press any key to exit"); - Console.ReadKey(); - } - - private static void QueryFilesBySize() - { - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\"; - - // Take a snapshot of the file system. - System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(startFolder); - - // This method assumes that the application has discovery permissions - // for all folders under the specified path. - IEnumerable fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - //Return the size of the largest file - long maxSize = - (from file in fileList - let len = GetFileLength(file) - select len) - .Max(); - - Console.WriteLine("The length of the largest file under {0} is {1}", - startFolder, maxSize); - - // Return the FileInfo object for the largest file - // by sorting and selecting from beginning of list - System.IO.FileInfo longestFile = - (from file in fileList - let len = GetFileLength(file) - where len > 0 - orderby len descending - select file) - .First(); - - Console.WriteLine("The largest file under {0} is {1} with a length of {2} bytes", - startFolder, longestFile.FullName, longestFile.Length); - - //Return the FileInfo of the smallest file - System.IO.FileInfo smallestFile = - (from file in fileList - let len = GetFileLength(file) - where len > 0 - orderby len ascending - select file).First(); - - Console.WriteLine("The smallest file under {0} is {1} with a length of {2} bytes", - startFolder, smallestFile.FullName, smallestFile.Length); - - //Return the FileInfos for the 10 largest files - // queryTenLargest is an IEnumerable - var queryTenLargest = - (from file in fileList - let len = GetFileLength(file) - orderby len descending - select file).Take(10); - - Console.WriteLine("The 10 largest files under {0} are:", startFolder); - - foreach (var v in queryTenLargest) - { - Console.WriteLine("{0}: {1} bytes", v.FullName, v.Length); - } - - // Group the files according to their size, leaving out - // files that are less than 200000 bytes. - var querySizeGroups = - from file in fileList - let len = GetFileLength(file) - where len > 0 - group file by (len / 100000) into fileGroup - where fileGroup.Key >= 2 - orderby fileGroup.Key descending - select fileGroup; - - foreach (var filegroup in querySizeGroups) - { - Console.WriteLine(filegroup.Key.ToString() + "00000"); - foreach (var item in filegroup) - { - Console.WriteLine("\t{0}: {1}", item.Name, item.Length); - } - } - } - - // This method is used to swallow the possible exception - // that can be raised when accessing the FileInfo.Length property. - // In this particular case, it is safe to swallow the exception. - static long GetFileLength(System.IO.FileInfo fi) - { - long retval; - try - { - retval = fi.Length; - } - catch (System.IO.FileNotFoundException) - { - // If a file is no longer present, - // just add zero bytes to the total. - retval = 0; - } - return retval; - } - -} -``` - - To return one or more complete objects, the query first must examine each one in the data source, and then sort them by the value of their Length property. Then it can return the single one or the sequence with the greatest lengths. Use to return the first element in a list. Use to return the first n number of elements. Specify a descending sort order to put the smallest elements at the start of the list. - - The query calls out to a separate method to obtain the file size in bytes in order to consume the possible exception that will be raised in the case where a file was deleted on another thread in the time period since the object was created in the call to `GetFiles`. Even through the object has already been created, the exception can occur because a object will try to refresh its property by using the most current size in bytes the first time the property is accessed. By putting this operation in a try-catch block outside the query, we follow the rule of avoiding operations in queries that can cause side-effects. In general, great care must be taken when consuming exceptions, to make sure that an application is not left in an unknown state. - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders-linq.md deleted file mode 100644 index 386559e9cb258..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders-linq.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "How to query for the total Number of bytes in a set of folders (LINQ) (C#)" -description: Learn how to use LINQ in C# to find the total number of bytes used by all the files in a specified folder and its subfolders. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: a01bd1d4-133c-4ca2-aa4e-e93e81d6076c ---- -# How to query for the total number of bytes in a set of folders (LINQ) (C#) - -This example shows how to retrieve the total number of bytes used by all the files in a specified folder and all its subfolders. - -## Example - - The method adds the values of all the items selected in the `select` clause. You can easily modify this query to retrieve the biggest or smallest file in the specified directory tree by calling the or method instead of . - -```csharp -class QuerySize -{ - public static void Main() - { - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\VC#"; - - // Take a snapshot of the file system. - // This method assumes that the application has discovery permissions - // for all folders under the specified path. - IEnumerable fileList = System.IO.Directory.GetFiles(startFolder, "*.*", System.IO.SearchOption.AllDirectories); - - var fileQuery = from file in fileList - select GetFileLength(file); - - // Cache the results to avoid multiple trips to the file system. - long[] fileLengths = fileQuery.ToArray(); - - // Return the size of the largest file - long largestFile = fileLengths.Max(); - - // Return the total number of bytes in all the files under the specified folder. - long totalBytes = fileLengths.Sum(); - - Console.WriteLine("There are {0} bytes in {1} files under {2}", - totalBytes, fileList.Count(), startFolder); - Console.WriteLine("The largest files is {0} bytes.", largestFile); - } - - // This method is used to swallow the possible exception - // that can be raised when accessing the System.IO.FileInfo.Length property. - static long GetFileLength(string filename) - { - long retval; - try - { - System.IO.FileInfo fi = new System.IO.FileInfo(filename); - retval = fi.Length; - } - catch (System.IO.FileNotFoundException) - { - // If a file is no longer present, - // just add zero bytes to the total. - retval = 0; - } - return retval; - } -} -``` - - If you only have to count the number of bytes in a specified directory tree, you can do this more efficiently without creating a LINQ query, which incurs the overhead of creating the list collection as a data source. The usefulness of the LINQ approach increases as the query becomes more complex, or when you have to run multiple queries against the same data source. - - The query calls out to a separate method to obtain the file length. It does this in order to consume the possible exception that will be raised if the file was deleted on another thread after the object was created in the call to `GetFiles`. Even though the object has already been created, the exception can occur because a object will try to refresh its property with the most current length the first time the property is accessed. By putting this operation in a try-catch block outside the query, the code follows the rule of avoiding operations in queries that can cause side-effects. In general, great care must be taken when you consume exceptions to make sure that an application is not left in an unknown state. - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-the-contents-of-files-in-a-folder-lin.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-the-contents-of-files-in-a-folder-lin.md deleted file mode 100644 index fd7fcb4bd895e..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-the-contents-of-files-in-a-folder-lin.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "How to query the contents of text files in a folder (LINQ) (C#)" -description: Learn how to use LINQ in C# to query over all the files in a directory tree, open each file, and inspect its contents. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: f5b4dce7-1a34-4eb4-9bf1-60d5bdda264c ---- -# How to query the contents of text files in a folder (LINQ) (C#) - -This example shows how to query over all the files in a specified directory tree, open each file, and inspect its contents. This type of technique could be used to create indexes or reverse indexes of the contents of a directory tree. A simple string search is performed in this example. However, more complex types of pattern matching can be performed with a regular expression. For more information, see [How to combine LINQ queries with regular expressions (C#)](./how-to-combine-linq-queries-with-regular-expressions.md). - -## Example - -```csharp -class QueryContents -{ - public static void Main() - { - // Modify this path as necessary. - string startFolder = @"c:\program files\Microsoft Visual Studio 9.0\"; - - // Take a snapshot of the file system. - System.IO.DirectoryInfo dir = new System.IO.DirectoryInfo(startFolder); - - // This method assumes that the application has discovery permissions - // for all folders under the specified path. - IEnumerable fileList = dir.GetFiles("*.*", System.IO.SearchOption.AllDirectories); - - string searchTerm = @"Visual Studio"; - - // Search the contents of each file. - // A regular expression created with the RegEx class - // could be used instead of the Contains method. - // queryMatchingFiles is an IEnumerable. - var queryMatchingFiles = - from file in fileList - where file.Extension == ".htm" - let fileText = GetFileText(file.FullName) - where fileText.Contains(searchTerm) - select file.FullName; - - // Execute the query. - Console.WriteLine("The term \"{0}\" was found in:", searchTerm); - foreach (string filename in queryMatchingFiles) - { - Console.WriteLine(filename); - } - } - - // Read the contents of the file. - static string GetFileText(string name) - { - string fileContents = String.Empty; - - // If the file has been deleted since we took - // the snapshot, ignore it and return the empty string. - if (System.IO.File.Exists(name)) - { - fileContents = System.IO.File.ReadAllText(name); - } - return fileContents; - } -} -``` - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file-linq.md deleted file mode 100644 index 4d180e121c07b..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file-linq.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "How to reorder the fields of a delimited file (LINQ) (C#)" -description: Learn how to rearrange fields in a .csv file in LINQ in C#. The example changes orders of columns, merges to columns, and sorts the rows by a column value. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 4e62d82c-61b7-4f18-b9a1-86723746d7d2 ---- -# How to reorder the fields of a delimited file (LINQ) (C#) - -A comma-separated value (CSV) file is a text file that is often used to store spreadsheet data or other tabular data that is represented by rows and columns. By using the method to separate the fields, it is very easy to query and manipulate CSV files by using LINQ. In fact, the same technique can be used to reorder the parts of any structured line of text; it is not limited to CSV files. - - In the following example, assume that the three columns represent students' "last name," "first name", and "ID." The fields are in alphabetical order based on the students' last names. The query produces a new sequence in which the ID column appears first, followed by a second column that combines the student's first name and last name. The lines are reordered according to the ID field. The results are saved into a new file and the original data is not modified. - -### To create the data file - -1. Copy the following lines into a plain text file that is named spreadsheet1.csv. Save the file in your project folder. - - ```csv - Adams,Terry,120 - Fakhouri,Fadi,116 - Feng,Hanying,117 - Garcia,Cesar,114 - Garcia,Debra,115 - Garcia,Hugo,118 - Mortensen,Sven,113 - O'Donnell,Claire,112 - Omelchenko,Svetlana,111 - Tucker,Lance,119 - Tucker,Michael,122 - Zabokritski,Eugene,121 - ``` - -## Example - -```csharp -class CSVFiles -{ - static void Main(string[] args) - { - // Create the IEnumerable data source - string[] lines = System.IO.File.ReadAllLines(@"../../../spreadsheet1.csv"); - - // Create the query. Put field 2 first, then - // reverse and combine fields 0 and 1 from the old field - IEnumerable query = - from line in lines - let x = line.Split(',') - orderby x[2] - select x[2] + ", " + (x[1] + " " + x[0]); - - // Execute the query and write out the new file. Note that WriteAllLines - // takes a string[], so ToArray is called on the query. - System.IO.File.WriteAllLines(@"../../../spreadsheet2.csv", query.ToArray()); - - Console.WriteLine("Spreadsheet2.csv written to disk. Press any key to exit"); - Console.ReadKey(); - } -} -/* Output to spreadsheet2.csv: -111, Svetlana Omelchenko -112, Claire O'Donnell -113, Sven Mortensen -114, Cesar Garcia -115, Debra Garcia -116, Fadi Fakhouri -117, Hanying Feng -118, Hugo Garcia -119, Lance Tucker -120, Terry Adams -121, Eugene Zabokritski -122, Michael Tucker - */ -``` - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md deleted file mode 100644 index 588ed783ea6c5..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "How to sort or filter text data by any word or field (LINQ) (C#)" -description: Learn how to sort or filter text data by any word or field. See an example for sorting lines of structured text by any field in the line. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 7c04d42f-4a78-42c8-9ec8-57ef18fe13a9 ---- -# How to sort or filter text data by any word or field (LINQ) (C#) - -The following example shows how to sort lines of structured text, such as comma-separated values, by any field in the line. The field may be dynamically specified at run time. Assume that the fields in scores.csv represent a student's ID number, followed by a series of four test scores. - -### To create a file that contains data - -1. Copy the scores.csv data from the topic [How to join content from dissimilar files (LINQ) (C#)](./how-to-join-content-from-dissimilar-files-linq.md) and save it to your solution folder. - -## Example - -```csharp -public class SortLines -{ - static void Main() - { - // Create an IEnumerable data source - string[] scores = System.IO.File.ReadAllLines(@"../../../scores.csv"); - - // Change this to any value from 0 to 4. - int sortField = 1; - - Console.WriteLine("Sorted highest to lowest by field [{0}]:", sortField); - - // Demonstrates how to return query from a method. - // The query is executed here. - foreach (string str in RunQuery(scores, sortField)) - { - Console.WriteLine(str); - } - } - - // Returns the query variable, not query results! - static IEnumerable RunQuery(IEnumerable source, int num) - { - // Split the string and sort on field[num] - var scoreQuery = from line in source - let fields = line.Split(',') - orderby fields[num] descending - select line; - - return scoreQuery; - } -} -/* Output (if sortField == 1): - Sorted highest to lowest by field [1]: - 116, 99, 86, 90, 94 - 120, 99, 82, 81, 79 - 111, 97, 92, 81, 60 - 114, 97, 89, 85, 82 - 121, 96, 85, 91, 60 - 122, 94, 92, 91, 91 - 117, 93, 92, 80, 87 - 118, 92, 90, 83, 78 - 113, 88, 94, 65, 91 - 112, 75, 84, 91, 39 - 119, 68, 79, 88, 92 - 115, 35, 72, 91, 70 - */ -``` - - This example also demonstrates how to return a query variable from a method. - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md deleted file mode 100644 index 5095e11373979..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: "How to split a file into many files by using groups (LINQ) (C#)" -description: Learn how to split a file into many files by using groups. See a code example and view additional available resources. -ms.topic: how-to -ms.date: 07/20/2015 -ms.assetid: 8179b91c-d778-4e57-884f-77fe5a8e4e40 ---- -# How to split a file into many files by using groups (LINQ) (C#) - -This example shows one way to merge the contents of two files and then create a set of new files that organize the data in a new way. - -### To create the data files - -1. Copy these names into a text file that is named names1.txt and save it in your project folder: - - ```text - Bankov, Peter - Holm, Michael - Garcia, Hugo - Potra, Cristina - Noriega, Fabricio - Aw, Kam Foo - Beebe, Ann - Toyoshima, Tim - Guy, Wey Yuan - Garcia, Debra - ``` - -2. Copy these names into a text file that is named names2.txt and save it in your project folder: Note that the two files have some names in common. - - ```text - Liu, Jinghao - Bankov, Peter - Holm, Michael - Garcia, Hugo - Beebe, Ann - Gilchrist, Beth - Myrcha, Jacek - Giakoumakis, Leo - McLin, Nkenge - El Yassir, Mehdi - ``` - -## Example - -```csharp -class SplitWithGroups -{ - static void Main() - { - string[] fileA = System.IO.File.ReadAllLines(@"../../../names1.txt"); - string[] fileB = System.IO.File.ReadAllLines(@"../../../names2.txt"); - - // Concatenate and remove duplicate names based on - // default string comparer - var mergeQuery = fileA.Union(fileB); - - // Group the names by the first letter in the last name. - var groupQuery = from name in mergeQuery - let n = name.Split(',') - group name by n[0][0] into g - orderby g.Key - select g; - - // Create a new file for each group that was created - // Note that nested foreach loops are required to access - // individual items with each group. - foreach (var g in groupQuery) - { - // Create the new file name. - string fileName = @"../../../testFile_" + g.Key + ".txt"; - - // Output to display. - Console.WriteLine(g.Key); - - // Write file. - using (System.IO.StreamWriter sw = new System.IO.StreamWriter(fileName)) - { - foreach (var item in g) - { - sw.WriteLine(item); - // Output to console for example purposes. - Console.WriteLine(" {0}", item); - } - } - } - // Keep console window open in debug mode. - Console.WriteLine("Files have been written. Press any key to exit"); - Console.ReadKey(); - } -} -/* Output: - A - Aw, Kam Foo - B - Bankov, Peter - Beebe, Ann - E - El Yassir, Mehdi - G - Garcia, Hugo - Guy, Wey Yuan - Garcia, Debra - Gilchrist, Beth - Giakoumakis, Leo - H - Holm, Michael - L - Liu, Jinghao - M - Myrcha, Jacek - McLin, Nkenge - N - Noriega, Fabricio - P - Potra, Cristina - T - Toyoshima, Tim - */ -``` - - The program writes a separate file for each group in the same folder as the data files. - -## Compiling the Code - -Create a C# console application project, with `using` directives for the System.Linq and System.IO namespaces. - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md b/docs/csharp/programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md deleted file mode 100644 index 9f7def108a69a..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: "Querying based on runtime state (C#)" -description: Describes various techniques your C# code can use to query dynamically depending on runtime state, by varying either LINQ method calls or the expression trees passed into those methods. -ms.topic: how-to -ms.date: 02/11/2021 -ms.assetid: 52cd44dd-a3ec-441e-b93a-4eca388119c7 ---- -# Querying based on runtime state (C#) - -> [!NOTE] -> Make sure you add `using System.Linq.Expressions;` and `using static System.Linq.Expressions.Expression;` at the top of your *.cs* file. - -Consider code that defines an or an [IQueryable\]() against a data source: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Initialize"::: - -Every time you run this code, the same exact query will be executed. This is frequently not very useful, as you may want your code to execute different queries depending on conditions at run time. This article describes how you can execute a different query based on runtime state. - -## IQueryable / IQueryable\ and expression trees - -Fundamentally, an has two components: - -* —a language- and datasource-agnostic representation of the current query's components, in the form of an expression tree. -* —an instance of a LINQ provider, which knows how to materialize the current query into a value or set of values. - -In the context of dynamic querying, the provider will usually remain the same; the expression tree of the query will differ from query to query. - -Expression trees are immutable; if you want a different expression tree—and thus a different query—you'll need to translate the existing expression tree to a new one, and thus to a new . - -The following sections describe specific techniques for querying differently in response to runtime state: - -- Use runtime state from within the expression tree -- Call additional LINQ methods -- Vary the expression tree passed into the LINQ methods -- Construct an [Expression\](xref:System.Linq.Expressions.Expression%601) expression tree using the factory methods at -- Add method call nodes to an 's expression tree -- Construct strings, and use the [Dynamic LINQ library](https://dynamic-linq.net/) - -## Use runtime state from within the expression tree - -Assuming the LINQ provider supports it, the simplest way to query dynamically is to reference the runtime state directly in the query via a closed-over variable, such as `length` in the following code example: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Runtime_state_from_within_expression_tree"::: - -The internal expression tree—and thus the query—haven't been modified; the query returns different values only because the value of `length` has been changed. - -## Call additional LINQ methods - -Generally, the [built-in LINQ methods](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Linq.Queryable/src/System/Linq/Queryable.cs) at perform two steps: - -* Wrap the current expression tree in a representing the method call. -* Pass the wrapped expression tree back to the provider, either to return a value via the provider's method; or to return a translated query object via the method. - -You can replace the original query with the result of an [IQueryable\](xref:System.Linq.IQueryable%601)-returning method, to get a new query. You can do this conditionally based on runtime state, as in the following example: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Added_method_calls"::: - -## Vary the expression tree passed into the LINQ methods - -You can pass in different expressions to the LINQ methods, depending on runtime state: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Varying_expressions"::: - -You might also want to compose the various subexpressions using a third-party library such as [LinqKit](http://www.albahari.com/nutshell/linqkit.aspx)'s [PredicateBuilder](http://www.albahari.com/nutshell/predicatebuilder.aspx): - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Compose_expressions"::: - -## Construct expression trees and queries using factory methods - -In all the examples up to this point, we've known the element type at compile time—`string`—and thus the type of the query—`IQueryable`. You may need to add components to a query of any element type, or to add different components, depending on the element type. You can create expression trees from the ground up, using the factory methods at , and thus tailor the expression at run time to a specific element type. - -### Constructing an [Expression\](xref:System.Linq.Expressions.Expression%601) - -When you construct an expression to pass into one of the LINQ methods, you're actually constructing an instance of [Expression\](xref:System.Linq.Expressions.Expression%601), where `TDelegate` is some delegate type such as `Func`, `Action`, or a custom delegate type. - -[Expression\](xref:System.Linq.Expressions.Expression%601) inherits from , which represents a complete lambda expression like the following: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Compiler_generated_expression_tree"::: - -A has two components: - -* A parameter list—`(string x)`—represented by the property. -* A body—`x.StartsWith("a")`—represented by the property. - -The basic steps in constructing an [Expression\](xref:System.Linq.Expressions.Expression%601) are as follows: - -* Define objects for each of the parameters (if any) in the lambda expression, using the factory method. - - :::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Factory_method_expression_tree_parameter"::: - -* Construct the body of your , using the (s) you've defined, and the factory methods at . For instance, an expression representing `x.StartsWith("a")` could be constructed like this: - - :::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Factory_method_expression_tree_body"::: - -* Wrap the parameters and body in a compile-time-typed [Expression\](xref:System.Linq.Expressions.Expression%601), using the appropriate factory method overload: - - :::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Factory_method_expression_tree_lambda"::: - -The following sections describe a scenario in which you might want to construct an [Expression\](xref:System.Linq.Expressions.Expression%601) to pass into a LINQ method, and provide a complete example of how to do so using the factory methods. - -### Scenario - -Let's say you have multiple entity types: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Entities"::: - -For any of these entity types, you want to filter and return only those entities that have a given text inside one of their `string` fields. For `Person`, you'd want to search the `FirstName` and `LastName` properties: - -```csharp -string term = /* ... */; -var personsQry = new List() - .AsQueryable() - .Where(x => x.FirstName.Contains(term) || x.LastName.Contains(term)); -``` - -But for `Car`, you'd want to search only the `Model` property: - -```csharp -string term = /* ... */; -var carsQry = new List() - .AsQueryable() - .Where(x => x.Model.Contains(term)); -``` - -While you could write one custom function for `IQueryable` and another for `IQueryable`, the following function adds this filtering to any existing query, irrespective of the specific element type. - -### Example - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Factory_methods_expression_of_tdelegate"::: - -Because the `TextFilter` function takes and returns an [IQueryable\](xref:System.Linq.IQueryable%601) (and not just an ), you can add further compile-time-typed query elements after the text filter. - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Factory_methods_expression_of_tdelegate_usage"::: - -## Add method call nodes to the 's expression tree - -If you have an instead of an [IQueryable\](xref:System.Linq.IQueryable%601), you can't directly call the generic LINQ methods. One alternative is to build the inner expression tree as above, and use reflection to invoke the appropriate LINQ method while passing in the expression tree. - -You could also duplicate the LINQ method's functionality, by wrapping the entire tree in a that represents a call to the LINQ method: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Factory_methods_lambdaexpression"::: - -In this case, you don't have a compile-time `T` generic placeholder, so you'll use the overload that doesn't require compile-time type information, and which produces a instead of an [Expression\](xref:System.Linq.Expressions.Expression%601). - -## The Dynamic LINQ library - -Constructing expression trees using factory methods is relatively complex; it is easier to compose strings. The [Dynamic LINQ library](https://dynamic-linq.net/) exposes a set of extension methods on corresponding to the standard LINQ methods at , and which accept strings in a [special syntax](https://dynamic-linq.net/expression-language) instead of expression trees. The library generates the appropriate expression tree from the string, and can return the resultant translated . - -For instance, the previous example could be rewritten as follows: - -:::code language="csharp" source="../../../../../samples/snippets/csharp/programming-guide/dynamic-linq-expression-trees/Program.cs" id="Dynamic_linq"::: - -## See also - -- [Execute expression trees](../../../advanced-topics/expression-trees/expression-trees-execution.md) -- [Dynamically specify predicate filters at run time](../../../linq/dynamically-specify-predicate-filters-at-runtime.md) diff --git a/docs/csharp/programming-guide/concepts/linq/linq-and-file-directories.md b/docs/csharp/programming-guide/concepts/linq/linq-and-file-directories.md deleted file mode 100644 index 1148344674937..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/linq-and-file-directories.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "LINQ and file directories (C#)" -description: These C# LINQ resources for file system operations are not used to change the contents of the files or folders. -ms.date: 07/20/2015 -ms.assetid: b66c55e4-0f72-44e5-b086-519f9962335c ---- -# LINQ and file directories (C#) - -Many file system operations are essentially queries and are therefore well suited to the LINQ approach. - - The queries in this section are non-destructive. They are not used to change the contents of the original files or folders. This follows the rule that queries should not cause any side-effects. In general, any code (including queries that perform create / update / delete operators) that modifies source data should be kept separate from the code that just queries the data. - - This section contains the following topics: - - [How to query for files with a specified attribute or name (C#)](./how-to-query-for-files-with-a-specified-attribute-or-name.md)\ - Shows how to search for files by examining one or more properties of its object. - - [How to group files by extension (LINQ) (C#)](./how-to-group-files-by-extension-linq.md)\ - Shows how to return groups of object based on their file name extension. - - [How to query for the total number of bytes in a set of folders (LINQ) (C#)](./how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders-linq.md)\ - Shows how to return the total number of bytes in all the files in a specified directory tree. - - [How to compare the contents of two folders (LINQ) (C#)](./how-to-compare-the-contents-of-two-folders-linq.md)s - Shows how to return all the files that are present in two specified folders, and also all the files that are present in one folder but not the other. - - [How to query for the largest file or files in a directory tree (LINQ) (C#)](./how-to-query-for-the-largest-file-or-files-in-a-directory-tree-linq.md)\ - Shows how to return the largest or smallest file, or a specified number of files, in a directory tree. - - [How to query for duplicate files in a directory tree (LINQ) (C#)](./how-to-query-for-duplicate-files-in-a-directory-tree-linq.md)\ - Shows how to group for all file names that occur in more than one location in a specified directory tree. Also shows how to perform more complex comparisons based on a custom comparer. - - [How to query the contents of files in a folder (LINQ) (C#)](./how-to-query-the-contents-of-files-in-a-folder-lin.md)\ - Shows how to iterate through folders in a tree, open each file, and query the file's contents. - -## Comments - - There is some complexity involved in creating a data source that accurately represents the contents of the file system and handles exceptions gracefully. The examples in this section create a snapshot collection of objects that represents all the files under a specified root folder and all its subfolders. The actual state of each may change in the time between when you begin and end executing a query. For example, you can create a list of objects to use as a data source. If you try to access the `Length` property in a query, the object will try to access the file system to update the value of `Length`. If the file no longer exists, you will get a in your query, even though you are not querying the file system directly. Some queries in this section use a separate method that consumes these particular exceptions in certain cases. Another option is to keep your data source updated dynamically by using the . - \ No newline at end of file diff --git a/docs/csharp/programming-guide/concepts/linq/snippets/extensions/Program.cs b/docs/csharp/programming-guide/concepts/linq/snippets/extensions/Program.cs deleted file mode 100644 index 54aaa034f76a4..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/snippets/extensions/Program.cs +++ /dev/null @@ -1,63 +0,0 @@ -using Custom.Linq.Extensions; - -// -double[] numbers = [1.9, 2, 8, 4, 5.7, 6, 7.2, 0]; -var query = numbers.Median(); - -Console.WriteLine($"double: Median = {query}"); -// This code produces the following output: -// double: Median = 4.85 -// - -// -double[] numbers1 = [1.9, 2, 8, 4, 5.7, 6, 7.2, 0]; -var query1 = numbers1.Median(); - -Console.WriteLine($"double: Median = {query1}"); - -int[] numbers2 = [1, 2, 3, 4, 5]; -var query2 = numbers2.Median(); - -Console.WriteLine($"int: Median = {query2}"); -// This code produces the following output: -// double: Median = 4.85 -// int: Median = 3 -// - -// -int[] numbers3 = [1, 2, 3, 4, 5]; - -/* - You can use the num => num lambda expression as a parameter for the Median method - so that the compiler will implicitly convert its value to double. - If there is no implicit conversion, the compiler will display an error message. -*/ -var query3 = numbers3.Median(num => num); - -Console.WriteLine($"int: Median = {query3}"); - -string[] numbers4 = ["one", "two", "three", "four", "five"]; - -// With the generic overload, you can also use numeric properties of objects. -var query4 = numbers4.Median(str => str.Length); - -Console.WriteLine($"string: Median = {query4}"); -// This code produces the following output: -// int: Median = 3 -// string: Median = 4 -// - -// -string[] strings = ["a", "b", "c", "d", "e"]; - -var query5 = strings.AlternateElements(); - -foreach (var element in query5) -{ - Console.WriteLine(element); -} -// This code produces the following output: -// a -// c -// e -// diff --git a/docs/csharp/programming-guide/concepts/linq/snippets/linq-snippets.sln b/docs/csharp/programming-guide/concepts/linq/snippets/linq-snippets.sln deleted file mode 100644 index 74e1a0f816460..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/snippets/linq-snippets.sln +++ /dev/null @@ -1,25 +0,0 @@ - -Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio Version 17 -VisualStudioVersion = 17.0.31612.314 -MinimumVisualStudioVersion = 10.0.40219.1 -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "linq", "extensions\linq.csproj", "{5097A709-D209-45BF-8A1F-96667DE90C37}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Release|Any CPU = Release|Any CPU - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {5097A709-D209-45BF-8A1F-96667DE90C37}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {5097A709-D209-45BF-8A1F-96667DE90C37}.Debug|Any CPU.Build.0 = Debug|Any CPU - {5097A709-D209-45BF-8A1F-96667DE90C37}.Release|Any CPU.ActiveCfg = Release|Any CPU - {5097A709-D209-45BF-8A1F-96667DE90C37}.Release|Any CPU.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection - GlobalSection(ExtensibilityGlobals) = postSolution - SolutionGuid = {DEB164F0-9F8F-4880-ACCF-994BE3CD9105} - EndGlobalSection -EndGlobal diff --git a/docs/csharp/programming-guide/concepts/linq/walkthrough-writing-queries-linq.md b/docs/csharp/programming-guide/concepts/linq/walkthrough-writing-queries-linq.md deleted file mode 100644 index 08e46d3467341..0000000000000 --- a/docs/csharp/programming-guide/concepts/linq/walkthrough-writing-queries-linq.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: "Walkthrough: Writing Queries in C# (LINQ)" -description: This walkthrough shows how C# language features are used in LINQ query expressions. This article uses Visual Studio as a development environment. -ms.date: 07/20/2015 -ms.topic: tutorial -helpviewer_keywords: - - "LINQ [C#], walkthroughs" - - "LINQ [C#], writing queries" - - "queries [LINQ in C#], writing" - - "writing LINQ queries" -ms.assetid: 2962a610-419a-4276-9ec8-4b7f2af0c081 ---- -# Walkthrough: Writing Queries in C# (LINQ) - -This walkthrough demonstrates the C# language features that are used to write LINQ query expressions. - -## Create a C# Project - -> [!NOTE] -> The following instructions are for Visual Studio. If you are using a different development environment, create a console project with a reference to System.Core.dll and a `using` directive for the namespace. - -#### To create a project in Visual Studio - -1. Start Visual Studio. - -2. On the menu bar, choose **File**, **New**, **Project**. - - The **New Project** dialog box opens. - -3. Expand **Installed**, expand **Templates**, expand **Visual C#**, and then choose **Console Application**. - -4. In the **Name** text box, enter a different name or accept the default name, and then choose the **OK** button. - - The new project appears in **Solution Explorer**. - -5. Notice that your project has a reference to System.Core.dll and a `using` directive for the namespace. - -## Create an in-Memory Data Source - - The data source for the queries is a simple list of `Student` objects. Each `Student` record has a first name, last name, and an array of integers that represents their test scores in the class. Copy this code into your project. Note the following characteristics: - -- The `Student` class consists of auto-implemented properties. - -- Each student in the list is initialized with an object initializer. - -- The list itself is initialized with a collection initializer. - - This whole data structure will be initialized and instantiated without explicit calls to any constructor or explicit member access. For more information about these new features, see [Auto-Implemented Properties](../../classes-and-structs/auto-implemented-properties.md) and [Object and Collection Initializers](../../classes-and-structs/object-and-collection-initializers.md). - -#### To add the data source - -- Add the `Student` class and the initialized list of students to the `Program` class in your project. - - [!code-csharp[CsLinqGettingStarted#11](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#11)] - -#### To add a new Student to the Students list - -1. Add a new `Student` to the `Students` list and use a name and test scores of your choice. Try typing all the new student information in order to better learn the syntax for the object initializer. - -## Create the Query - -#### To create a simple query - -- In the application's `Main` method, create a simple query that, when it is executed, will produce a list of all students whose score on the first test was greater than 90. Note that because the whole `Student` object is selected, the type of the query is `IEnumerable`. Although the code could also use implicit typing by using the [var](../../../language-reference/statements/declarations.md#implicitly-typed-local-variables) keyword, explicit typing is used to clearly illustrate results. (For more information about `var`, see [Implicitly Typed Local Variables](../../classes-and-structs/implicitly-typed-local-variables.md).) - - Note also that the query's range variable, `student`, serves as a reference to each `Student` in the source, providing member access for each object. - - [!code-csharp[CsLINQGettingStarted#12](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#12)] - -## Execute the Query - -#### To execute the query - -1. Now write the `foreach` loop that will cause the query to execute. Note the following about the code: - - - Each element in the returned sequence is accessed through the iteration variable in the `foreach` loop. - - - The type of this variable is `Student`, and the type of the query variable is compatible, `IEnumerable`. - -2. After you have added this code, build and run the application to see the results in the **Console** window. - - [!code-csharp[CsLINQGettingStarted#13](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#13)] - -#### To add another filter condition - -1. You can combine multiple Boolean conditions in the `where` clause in order to further refine a query. The following code adds a condition so that the query returns those students whose first score was over 90 and whose last score was less than 80. The `where` clause should resemble the following code. - - ```csharp - where student.Scores[0] > 90 && student.Scores[3] < 80 - ``` - - For more information, see [where clause](../../../language-reference/keywords/where-clause.md). - -## Modify the Query - -#### To order the results - -1. It will be easier to scan the results if they are in some kind of order. You can order the returned sequence by any accessible field in the source elements. For example, the following `orderby` clause orders the results in alphabetical order from A to Z according to the last name of each student. Add the following `orderby` clause to your query, right after the `where` statement and before the `select` statement: - - ```csharp - orderby student.Last ascending - ``` - -2. Now change the `orderby` clause so that it orders the results in reverse order according to the score on the first test, from the highest score to the lowest score. - - ```csharp - orderby student.Scores[0] descending - ``` - -3. Change the `WriteLine` format string so that you can see the scores: - - ```csharp - Console.WriteLine("{0}, {1} {2}", student.Last, student.First, student.Scores[0]); - ``` - - For more information, see [orderby clause](../../../language-reference/keywords/orderby-clause.md). - -#### To group the results - -1. Grouping is a powerful capability in query expressions. A query with a group clause produces a sequence of groups, and each group itself contains a `Key` and a sequence that consists of all the members of that group. The following new query groups the students by using the first letter of their last name as the key. - - [!code-csharp[CsLINQGettingStarted#14](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#14)] - -2. Note that the type of the query has now changed. It now produces a sequence of groups that have a `char` type as a key, and a sequence of `Student` objects. Because the type of the query has changed, the following code changes the `foreach` execution loop also: - - [!code-csharp[CsLINQGettingStarted#15](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#15)] - -3. Run the application and view the results in the **Console** window. - - For more information, see [group clause](../../../language-reference/keywords/group-clause.md). - -#### To make the variables implicitly typed - -1. Explicitly coding `IEnumerables` of `IGroupings` can quickly become tedious. You can write the same query and `foreach` loop much more conveniently by using `var`. The `var` keyword does not change the types of your objects; it just instructs the compiler to infer the types. Change the type of `studentQuery` and the iteration variable `group` to `var` and rerun the query. Note that in the inner `foreach` loop, the iteration variable is still typed as `Student`, and the query works just as before. Change the `student` iteration variable to `var` and run the query again. You see that you get exactly the same results. - - [!code-csharp[CsLINQGettingStarted#16](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#16)] - - For more information about [var](../../../language-reference/statements/declarations.md#implicitly-typed-local-variables), see [Implicitly Typed Local Variables](../../classes-and-structs/implicitly-typed-local-variables.md). - -#### To order the groups by their key value - -1. When you run the previous query, you notice that the groups are not in alphabetical order. To change this, you must provide an `orderby` clause after the `group` clause. But to use an `orderby` clause, you first need an identifier that serves as a reference to the groups created by the `group` clause. You provide the identifier by using the `into` keyword, as follows: - - [!code-csharp[csLINQGettingStarted#17](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#17)] - - When you run this query, you will see the groups are now sorted in alphabetical order. - -#### To introduce an identifier by using let - -1. You can use the `let` keyword to introduce an identifier for any expression result in the query expression. This identifier can be a convenience, as in the following example, or it can enhance performance by storing the results of an expression so that it does not have to be calculated multiple times. - - [!code-csharp[csLINQGettingStarted#18](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#18)] - - For more information, see [let clause](../../../language-reference/keywords/let-clause.md). - -#### To use method syntax in a query expression - -1. As described in [Query Syntax and Method Syntax in LINQ](../../../linq/get-started/write-linq-queries.md), some query operations can only be expressed by using method syntax. The following code calculates the total score for each `Student` in the source sequence, and then calls the `Average()` method on the results of that query to calculate the average score of the class. - - [!code-csharp[csLINQGettingStarted#19](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#19)] - -#### To transform or project in the select clause - -1. It is very common for a query to produce a sequence whose elements differ from the elements in the source sequences. Delete or comment out your previous query and execution loop, and replace it with the following code. Note that the query returns a sequence of strings (not `Students`), and this fact is reflected in the `foreach` loop. - - [!code-csharp[csLINQGettingStarted#20](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#20)] - -2. Code earlier in this walkthrough indicated that the average class score is approximately 334. To produce a sequence of `Students` whose total score is greater than the class average, together with their `Student ID`, you can use an anonymous type in the `select` statement: - - [!code-csharp[csLINQGettingStarted#21](~/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs#21)] - -## Next Steps - - After you are familiar with the basic aspects of working with queries in C#, you are ready to read the documentation and samples for the specific type of LINQ provider you are interested in: - - [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) - - [LINQ to DataSet](../../../../framework/data/adonet/linq-to-dataset.md) - - [LINQ to XML (C#)](../../../../standard/linq/linq-xml-overview.md) - - [LINQ to Objects (C#)](../../../linq/query-a-collection-of-objects.md) - -## See also - -- [Language-Integrated Query (LINQ) (C#)](/dotnet/csharp/linq/) -- [LINQ Query Expressions](../../../linq/index.md) diff --git a/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md b/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md index 978946f0312a3..a5020cbfa4de0 100644 --- a/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md +++ b/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md @@ -13,7 +13,7 @@ ms.assetid: 9310ae16-8627-44a2-b08c-05e5976202b1 The following procedure demonstrates how to add events that follow the standard .NET pattern to your classes and structs. All events in the .NET class library are based on the delegate, which is defined as follows: ```csharp -public delegate void EventHandler(object sender, EventArgs e); +public delegate void EventHandler(object? sender, EventArgs e); ``` > [!NOTE] @@ -42,7 +42,7 @@ The name `EventHandler` can lead to a bit of confusion as it doesn't actually ha 2. (Skip this step if you are using the generic version of .) Declare a delegate in your publishing class. Give it a name that ends with `EventHandler`. The second parameter specifies your custom `EventArgs` type. ```csharp - public delegate void CustomEventHandler(object sender, CustomEventArgs args); + public delegate void CustomEventHandler(object? sender, CustomEventArgs args); ``` 3. Declare the event in your publishing class by using one of the following steps. @@ -50,19 +50,19 @@ The name `EventHandler` can lead to a bit of confusion as it doesn't actually ha 1. If you have no custom EventArgs class, your Event type will be the non-generic EventHandler delegate. You do not have to declare the delegate because it is already declared in the namespace that is included when you create your C# project. Add the following code to your publisher class. ```csharp - public event EventHandler RaiseCustomEvent; + public event EventHandler? RaiseCustomEvent; ``` 2. If you are using the non-generic version of and you have a custom class derived from , declare your event inside your publishing class and use your delegate from step 2 as the type. ```csharp - public event CustomEventHandler RaiseCustomEvent; + public event CustomEventHandler? RaiseCustomEvent; ``` 3. If you are using the generic version, you do not need a custom delegate. Instead, in your publishing class, you specify your event type as `EventHandler`, substituting the name of your own class between the angle brackets. ```csharp - public event EventHandler RaiseCustomEvent; + public event EventHandler? RaiseCustomEvent; ``` ## Example diff --git a/docs/csharp/programming-guide/generics/generics-in-the-run-time.md b/docs/csharp/programming-guide/generics/generics-in-the-run-time.md index 645a0580e2695..a9e4403e77167 100644 --- a/docs/csharp/programming-guide/generics/generics-in-the-run-time.md +++ b/docs/csharp/programming-guide/generics/generics-in-the-run-time.md @@ -2,48 +2,48 @@ title: "Generics in the runtime - C# Programming Guide" description: Learn about generic types in the runtime. See code examples and view additional available resources. ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "generics [C#], at run time" ms.assetid: 119df7e6-9ceb-49df-af36-24f8f8c0747f --- # Generics in the runtime (C# programming guide) -When a generic type or method is compiled into Microsoft intermediate language (MSIL), it contains metadata that identifies it as having type parameters. How the MSIL for a generic type is used differs based on whether the supplied type parameter is a value type or reference type. - - When a generic type is first constructed with a value type as a parameter, the runtime creates a specialized generic type with the supplied parameter or parameters substituted in the appropriate locations in the MSIL. Specialized generic types are created one time for each unique value type that is used as a parameter. - - For example, suppose your program code declared a stack that's constructed of integers: - +When a generic type or method is compiled into common intermediate language (CIL), it contains metadata that identifies it as having type parameters. How the CIL for a generic type is used differs based on whether the supplied type parameter is a value type or reference type. + + When a generic type is first constructed with a value type as a parameter, the runtime creates a specialized generic type with the supplied parameter or parameters substituted in the appropriate locations in the CIL. Specialized generic types are created one time for each unique value type that is used as a parameter. + + For example, suppose your program code declared a stack that's constructed of integers: + ```csharp Stack? stack; -``` - - At this point, the runtime generates a specialized version of the class that has the integer substituted appropriately for its parameter. Now, whenever your program code uses a stack of integers, the runtime reuses the generated specialized class. In the following example, two instances of a stack of integers are created, and they share a single instance of the `Stack` code: - - [!code-csharp[csProgGuideGenerics#43](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#43)] - - However, suppose that another class with a different value type such as a `long` or a user-defined structure as its parameter is created at another point in your code. As a result, the runtime generates another version of the generic type and substitutes a `long` in the appropriate locations in MSIL. Conversions are no longer necessary because each specialized generic class natively contains the value type. - - Generics work somewhat differently for reference types. The first time a generic type is constructed with any reference type, the runtime creates a specialized generic type with object references substituted for the parameters in the MSIL. Then, every time that a constructed type is instantiated with a reference type as its parameter, regardless of what type it is, the runtime reuses the previously created specialized version of the generic type. This is possible because all references are the same size. - - For example, suppose you had two reference types, a `Customer` class and an `Order` class, and also suppose that you created a stack of `Customer` types: - - [!code-csharp[csProgGuideGenerics#47](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#47)] - - [!code-csharp[csProgGuideGenerics#44](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#44)] - - At this point, the runtime generates a specialized version of the class that stores object references that will be filled in later instead of storing data. Suppose the next line of code creates a stack of another reference type, which is named `Order`: - - [!code-csharp[csProgGuideGenerics#45](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#45)] - - Unlike with value types, another specialized version of the class is not created for the `Order` type. Instead, an instance of the specialized version of the class is created and the `orders` variable is set to reference it. Suppose that you then encountered a line of code to create a stack of a `Customer` type: - - [!code-csharp[csProgGuideGenerics#46](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#46)] - - As with the previous use of the class created by using the `Order` type, another instance of the specialized class is created. The pointers that are contained therein are set to reference an area of memory the size of a `Customer` type. Because the number of reference types can vary wildly from program to program, the C# implementation of generics greatly reduces the amount of code by reducing to one the number of specialized classes created by the compiler for generic classes of reference types. - - Moreover, when a generic C# class is instantiated by using a value type or reference type parameter, reflection can query it at run time and both its actual type and its type parameter can be ascertained. - +``` + + At this point, the runtime generates a specialized version of the class that has the integer substituted appropriately for its parameter. Now, whenever your program code uses a stack of integers, the runtime reuses the generated specialized class. In the following example, two instances of a stack of integers are created, and they share a single instance of the `Stack` code: + + [!code-csharp[csProgGuideGenerics#43](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#43)] + + However, suppose that another class with a different value type such as a `long` or a user-defined structure as its parameter is created at another point in your code. As a result, the runtime generates another version of the generic type and substitutes a `long` in the appropriate locations in CIL. Conversions are no longer necessary because each specialized generic class natively contains the value type. + + Generics work somewhat differently for reference types. The first time a generic type is constructed with any reference type, the runtime creates a specialized generic type with object references substituted for the parameters in the CIL. Then, every time that a constructed type is instantiated with a reference type as its parameter, regardless of what type it is, the runtime reuses the previously created specialized version of the generic type. This is possible because all references are the same size. + + For example, suppose you had two reference types, a `Customer` class and an `Order` class, and also suppose that you created a stack of `Customer` types: + + [!code-csharp[csProgGuideGenerics#47](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#47)] + + [!code-csharp[csProgGuideGenerics#44](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#44)] + + At this point, the runtime generates a specialized version of the class that stores object references that will be filled in later instead of storing data. Suppose the next line of code creates a stack of another reference type, which is named `Order`: + + [!code-csharp[csProgGuideGenerics#45](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#45)] + + Unlike with value types, another specialized version of the class is not created for the `Order` type. Instead, an instance of the specialized version of the class is created and the `orders` variable is set to reference it. Suppose that you then encountered a line of code to create a stack of a `Customer` type: + + [!code-csharp[csProgGuideGenerics#46](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#46)] + + As with the previous use of the class created by using the `Order` type, another instance of the specialized class is created. The pointers that are contained therein are set to reference an area of memory the size of a `Customer` type. Because the number of reference types can vary wildly from program to program, the C# implementation of generics greatly reduces the amount of code by reducing to one the number of specialized classes created by the compiler for generic classes of reference types. + + Moreover, when a generic C# class is instantiated by using a value type or reference type parameter, reflection can query it at run time and both its actual type and its type parameter can be ascertained. + ## See also - diff --git a/docs/csharp/toc.yml b/docs/csharp/toc.yml index 32ad9dda58010..342102d9609f5 100644 --- a/docs/csharp/toc.yml +++ b/docs/csharp/toc.yml @@ -219,6 +219,8 @@ items: href: linq/get-started/type-relationships-in-linq-query-operations.md - name: C# features that support LINQ href: linq/get-started/features-that-support-linq.md + - name: "Tutorial: Writing queries in C#" + href: linq/get-started/walkthrough-writing-queries-linq.md - name: Standard query operators items: - name: Overview @@ -241,72 +243,18 @@ items: href: linq/standard-query-operators/join-operations.md - name: Group data href: linq/standard-query-operators/grouping-data.md - - name: LINQ to objects - href: linq/query-a-collection-of-objects.md - - name: Store the results of a query in memory - href: linq/store-the-results-of-a-query-in-memory.md - - name: "Walkthrough: Writing queries in C#" - href: programming-guide/concepts/linq/walkthrough-writing-queries-linq.md - - name: LINQ and file directories - items: - - name: Overview - href: programming-guide/concepts/linq/linq-and-file-directories.md - - name: "How to query for files with a specified attribute or name" - href: programming-guide/concepts/linq/how-to-query-for-files-with-a-specified-attribute-or-name.md - - name: "How to group files by extension" - href: programming-guide/concepts/linq/how-to-group-files-by-extension-linq.md - - name: "How to query for the total number of bytes in a set of folders" - href: programming-guide/concepts/linq/how-to-query-for-the-total-number-of-bytes-in-a-set-of-folders-linq.md - - name: "How to compare the contents of two folders" - href: programming-guide/concepts/linq/how-to-compare-the-contents-of-two-folders-linq.md - - name: "How to query for the largest file or files in a directory tree" - href: programming-guide/concepts/linq/how-to-query-for-the-largest-file-or-files-in-a-directory-tree-linq.md - - name: "How to query for duplicate files in a directory tree" - href: programming-guide/concepts/linq/how-to-query-for-duplicate-files-in-a-directory-tree-linq.md - - name: "How to query the contents of files in a folder" - href: programming-guide/concepts/linq/how-to-query-the-contents-of-files-in-a-folder-lin.md - name: How-to articles items: - - name: How to return a query from a method - href: linq/return-a-query-from-a-method.md - - name: Dynamically specify predicate filters at runtime - href: linq/dynamically-specify-predicate-filters-at-runtime.md - - name: Handle null values in query expressions - href: linq/handle-null-values-in-query-expressions.md - - name: Handle exceptions in query expressions - href: linq/handle-exceptions-in-query-expressions.md - - name: "How to count occurrences of a word in a string" - href: programming-guide/concepts/linq/how-to-count-occurrences-of-a-word-in-a-string-linq.md - - name: "How to query for sentences that contain a specified set of words" - href: programming-guide/concepts/linq/how-to-query-for-sentences-that-contain-a-specified-set-of-words-linq.md - - name: "How to query for characters in a string" - href: programming-guide/concepts/linq/how-to-query-for-characters-in-a-string-linq.md - - name: "How to combine LINQ queries with regular expressions" - href: programming-guide/concepts/linq/how-to-combine-linq-queries-with-regular-expressions.md - - name: "How to find the set difference between two lists" - href: programming-guide/concepts/linq/how-to-find-the-set-difference-between-two-lists-linq.md - - name: "How to sort or filter text data by any word or field" - href: programming-guide/concepts/linq/how-to-sort-or-filter-text-data-by-any-word-or-field-linq.md - - name: "How to reorder the fields of a delimited file" - href: programming-guide/concepts/linq/how-to-reorder-the-fields-of-a-delimited-file-linq.md - - name: "How to combine and compare string collections" - href: programming-guide/concepts/linq/how-to-combine-and-compare-string-collections-linq.md - - name: "How to populate object collections from multiple sources" - href: programming-guide/concepts/linq/how-to-populate-object-collections-from-multiple-sources-linq.md - - name: "How to split a file into many files by using groups" - href: programming-guide/concepts/linq/how-to-split-a-file-into-many-files-by-using-groups-linq.md - - name: "How to join content from dissimilar files" - href: programming-guide/concepts/linq/how-to-join-content-from-dissimilar-files-linq.md - - name: "How to compute column values in a CSV text file" - href: programming-guide/concepts/linq/how-to-compute-column-values-in-a-csv-text-file-linq.md - - name: "How to use expression trees to build dynamic queries" - href: programming-guide/concepts/linq/how-to-use-expression-trees-to-build-dynamic-queries.md - - name: "How to query an ArrayList with LINQ" - href: programming-guide/concepts/linq/how-to-query-an-arraylist-with-linq.md - - name: "How to add custom methods for LINQ queries" - href: programming-guide/concepts/linq/how-to-add-custom-methods-for-linq-queries.md - - name: How to group results by contiguous keys - href: linq/group-results-by-contiguous-keys.md + - name: "How to: LINQ and file directories" + href: linq/how-to-query-files-and-directories.md + - name: "How to: LINQ and strings" + href: linq/how-to-query-strings.md + - name: "How to: LINQ and collections" + href: linq/how-to-query-collections.md + - name: How to extend LINQ with new methods + href: linq/how-to-extend-linq.md + - name: How to build dynamic queries at run time + href: linq/how-to-build-dynamic-queries.md - name: Asynchronous programming items: - name: Overview diff --git a/docs/csharp/tour-of-csharp/tips-for-javascript-developers.md b/docs/csharp/tour-of-csharp/tips-for-javascript-developers.md index 8dd3c80228886..940600f2c061d 100644 --- a/docs/csharp/tour-of-csharp/tips-for-javascript-developers.md +++ b/docs/csharp/tour-of-csharp/tips-for-javascript-developers.md @@ -7,7 +7,7 @@ ms.date: 04/03/2024 C#, TypeScript and JavaScript are all members of the C family of languages. The similarities between the languages help you quickly become productive in C#. -1. ***Similar syntax***: JavaScript, TypeScript, and C# are in the C family of languages. That similarity means you can already read and understand C#. There are some differences, but most of the syntax is the same as JavaScript, and C. The curly braces and semicolons are familiar. The control statements like `if`, `else`, `switch` are the same. The looping statements of `for`, `while`, and `do`...`while` are same. The same keywords for `class`, `struct`, and `interface` are in both C# and TypeScript. The access modifiers in TypeScript and C#, from `public` to `private`, are the same. +1. ***Similar syntax***: JavaScript, TypeScript, and C# are in the C family of languages. That similarity means you can already read and understand C#. There are some differences, but most of the syntax is the same as JavaScript, and C. The curly braces and semicolons are familiar. The control statements like `if`, `else`, `switch` are the same. The looping statements of `for`, `while`, and `do`...`while` are same. The same keywords for `class` and `interface` are in both C# and TypeScript. The access modifiers in TypeScript and C#, from `public` to `private`, are the same. 1. ***The `=>` token***: All languages support lightweight function definitions. In C#, they're referred to as [*lambda expressions*](../language-reference/operators/lambda-expressions.md), in JavaScript, they're typically called *arrow functions*. 1. ***Function hierarchies***: All three languages support [local functions](../programming-guide/classes-and-structs/local-functions.md), which are functions defined in other functions. 1. ***Async / Await***: All three languages share the same `async` and `await` keywords for asynchronous programming. @@ -37,4 +37,4 @@ In addition, a few more TypeScript features aren't available in C#: 1. ***Decorators***: C# doesn't have decorators. Some common decorators, such as `@sealed` are reserved keywords in C#. Other common decorators might have corresponding [Attributes](../language-reference/attributes/general.md). For other decorators, you can create your own attributes. 1. ***More forgiving syntax***: The C# compiler parses code more strictly than JavaScript requires. -If you're building a web application, you should consider using [Blazor](/aspnet/core/blazor/index.md) to build your application. Blazor is a full-stack web framework built for .NET and C#. Blazor components can run on the server, as .NET assemblies, or on the client using WebAssembly. Blazor supports interop with your favorite JavaScript or TypeScript libraries. +If you're building a web application, you should consider using [Blazor](/aspnet/core/blazor/index) to build your application. Blazor is a full-stack web framework built for .NET and C#. Blazor components can run on the server, as .NET assemblies, or on the client using WebAssembly. Blazor supports interop with your favorite JavaScript or TypeScript libraries. diff --git a/docs/csharp/tutorials/ranges-indexes.md b/docs/csharp/tutorials/ranges-indexes.md index 01a106b9f641c..bbf4521a379d0 100644 --- a/docs/csharp/tutorials/ranges-indexes.md +++ b/docs/csharp/tutorials/ranges-indexes.md @@ -29,22 +29,9 @@ This language support relies on two new types and two new operators: - represents a sub range of a sequence. - The [range operator `..`](../language-reference/operators/member-access-operators.md#range-operator-), which specifies the start and end of a range as its operands. -Let's start with the rules for indices. Consider an array `sequence`. The `0` index is the same as `sequence[0]`. The `^0` index is the same as `sequence[sequence.Length]`. The expression `sequence[^0]` does throw an exception, just as `sequence[sequence.Length]` does. For any number `n`, the index `^n` is the same as `sequence.Length - n`. +Let's start with the rules for indices. Consider an array `sequence`. The `0` index is the same as `sequence[0]`. The `^0` index is the same as `sequence[sequence.Length]`. The expression `sequence[^0]` throws an exception, just as `sequence[sequence.Length]` does. For any number `n`, the index `^n` is the same as `sequence.Length - n`. -```csharp -string[] words = [ - // index from start index from end - "The", // 0 ^9 - "quick", // 1 ^8 - "brown", // 2 ^7 - "fox", // 3 ^6 - "jumps", // 4 ^5 - "over", // 5 ^4 - "the", // 6 ^3 - "lazy", // 7 ^2 - "dog" // 8 ^1 -]; // 9 (or words.Length) ^0 -``` +:::code language="csharp" source="snippets/RangesIndexes/IndicesAndRanges.cs" id="SnippetIndicesAndRanges_Initialization"::: You can retrieve the last word with the `^1` index. Add the following code below the initialization: @@ -52,11 +39,11 @@ You can retrieve the last word with the `^1` index. Add the following code below A range specifies the *start* and *end* of a range. The start of the range is inclusive, but the end of the range is exclusive, meaning the *start* is included in the range but the *end* isn't included in the range. The range `[0..^0]` represents the entire range, just as `[0..sequence.Length]` represents the entire range. -The following code creates a subrange with the words "quick", "brown", and "fox". It includes `words[1]` through `words[3]`. The element `words[4]` isn't in the range. +The following code creates a subrange with the words "second", "third", and "fourth". It includes `words[1]` through `words[3]`. The element `words[4]` isn't in the range. :::code language="csharp" source="snippets/RangesIndexes/IndicesAndRanges.cs" id="SnippetIndicesAndRanges_Range"::: -The following code returns the range with "lazy" and "dog". It includes `words[^2]` and `words[^1]`. The end index `words[^0]` isn't included. Add the following code as well: +The following code returns the range with "ninth" and "tenth". It includes `words[^2]` and `words[^1]`. The end index `words[^0]` isn't included. :::code language="csharp" source="snippets/RangesIndexes/IndicesAndRanges.cs" id="SnippetIndicesAndRanges_LastRange"::: diff --git a/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs b/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs index 13e8d9adff4aa..91563bd266ae5 100644 --- a/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs +++ b/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs @@ -4,23 +4,24 @@ class IndicesAndRanges { // private string[] words = [ - // index from start index from end - "The", // 0 ^9 - "quick", // 1 ^8 - "brown", // 2 ^7 - "fox", // 3 ^6 - "jumped", // 4 ^5 - "over", // 5 ^4 - "the", // 6 ^3 - "lazy", // 7 ^2 - "dog" // 8 ^1 - ]; + // index from start index from end + "first", // 0 ^10 + "second", // 1 ^9 + "third", // 2 ^8 + "fourth", // 3 ^7 + "fifth", // 4 ^6 + "sixth", // 5 ^5 + "seventh", // 6 ^4 + "eighth", // 7 ^3 + "ninth", // 8 ^2 + "tenth" // 9 ^1 + ]; // 10 (or words.Length) ^0 // internal int Syntax_LastIndex() { // - Console.WriteLine($"The last word is {words[^1]}"); + Console.WriteLine($"The last word is < {words[^1]} >."); // The last worid is < tenth >. // return 0; } @@ -28,9 +29,11 @@ internal int Syntax_LastIndex() internal int Syntax_Range() { // - string[] quickBrownFox = words[1..4]; - foreach (var word in quickBrownFox) - Console.Write($"< {word} >"); + string[] secondThirdFourth = words[1..4]; // contains "second", "third" and "fourth" + + // < first >< second >< third >< fourth > + foreach (var word in secondThirdFourth) + Console.Write($"< {word} >"); Console.WriteLine(); // return 0; @@ -39,9 +42,11 @@ internal int Syntax_Range() internal int Syntax_LastRange() { // - string[] lazyDog = words[^2..^0]; - foreach (var word in lazyDog) - Console.Write($"< {word} >"); + string[] lastTwo = words[^2..^0]; // contains "ninth" and "tenth" + + // < ninth >< tenth > + foreach (var word in lastTwo) + Console.Write($"< {word} >"); Console.WriteLine(); // return 0; @@ -50,17 +55,23 @@ internal int Syntax_LastRange() internal int Syntax_PartialRange() { // - string[] allWords = words[..]; // contains "The" through "dog". - string[] firstPhrase = words[..4]; // contains "The" through "fox" - string[] lastPhrase = words[6..]; // contains "the", "lazy" and "dog" + string[] allWords = words[..]; // contains "first" through "tenth". + string[] firstPhrase = words[..4]; // contains "first" through "fourth" + string[] lastPhrase = words[6..]; // contains "seventh", "eight", "ninth" and "tenth" + + // < first >< second >< third >< fourth >< fifth >< sixth >< seventh >< eighth >< ninth >< tenth > foreach (var word in allWords) - Console.Write($"< {word} >"); + Console.Write($"< {word} >"); Console.WriteLine(); + + // < first >< second >< third >< fourth > foreach (var word in firstPhrase) - Console.Write($"< {word} >"); + Console.Write($"< {word} >"); Console.WriteLine(); + + // < seventh >< eighth >< ninth >< tenth > foreach (var word in lastPhrase) - Console.Write($"< {word} >"); + Console.Write($"< {word} >"); Console.WriteLine(); // return 0; @@ -69,12 +80,14 @@ internal int Syntax_PartialRange() internal int Syntax_IndexRangeType() { // - Index the = ^3; - Console.WriteLine(words[the]); + Index thirdFromEnd = ^3; + Console.WriteLine($"< {words[thirdFromEnd]} > "); // < eighth > Range phrase = 1..4; string[] text = words[phrase]; + + // < second >< third >< fourth > foreach (var word in text) - Console.Write($"< {word} >"); + Console.Write($"< {word} >"); Console.WriteLine(); // return 0; diff --git a/docs/csharp/whats-new/csharp-version-history.md b/docs/csharp/whats-new/csharp-version-history.md index 7ed0ed155dfb9..7f741f206050d 100644 --- a/docs/csharp/whats-new/csharp-version-history.md +++ b/docs/csharp/whats-new/csharp-version-history.md @@ -290,7 +290,7 @@ C# version 7.0 was released with Visual Studio 2017. This version has some evolu Other features included: - [Discards](../fundamentals/functional/discards.md) -- Binary Literals and Digit Separators +- [Binary Literals and Digit Separators](../language-reference/builtin-types/integral-numeric-types.md#integer-literals) - [Throw expressions](../language-reference/statements/exception-handling-statements.md#the-throw-expression) All of these features offer new capabilities for developers and the opportunity to write cleaner code than ever. A highlight is condensing the declaration of variables to use with the `out` keyword and by allowing multiple return values via tuple. .NET Core now targets any operating system and has its eyes firmly on the cloud and on portability. These new capabilities certainly occupy the language designers' thoughts and time, in addition to coming up with new features. diff --git a/docs/framework/64-bit-apps.md b/docs/framework/64-bit-apps.md index 8aeffa7258639..e56c6674bd1c5 100644 --- a/docs/framework/64-bit-apps.md +++ b/docs/framework/64-bit-apps.md @@ -2,7 +2,7 @@ title: "64-bit Applications" description: Get information about configuring applications on a Windows 64-bit OS, as either a native 64-bit application or under WOW64 (Windows 32-bit on Windows 64-bit). ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "applications [C++], 64-bit" - "64-bit applications [C++]" - "64-bit programming [C++]" @@ -10,51 +10,51 @@ ms.assetid: fd4026bc-2c3d-4b27-86dc-ec5e96018181 --- # 64-bit Applications -When you compile an application, you can specify that it should run on a Windows 64-bit operating system either as a native application or under WOW64 (Windows 32-bit on Windows 64-bit). WOW64 is a compatibility environment that enables a 32-bit application to run on a 64-bit system. WOW64 is included in all 64-bit versions of the Windows operating system. - -## Running 32-bit vs. 64-bit Applications on Windows +When you compile an application, you can specify that it should run on a Windows 64-bit operating system either as a native application or under WOW64 (Windows 32-bit on Windows 64-bit). WOW64 is a compatibility environment that enables a 32-bit application to run on a 64-bit system. WOW64 is included in all 64-bit versions of the Windows operating system. + +## Running 32-bit vs. 64-bit Applications on Windows + + All applications that are built on the .NET Framework 1.0 or 1.1 are treated as 32-bit applications on a 64-bit operating system and are always executed under WOW64 and the 32-bit common language runtime (CLR). 32-bit applications that are built on the .NET Framework 4 or later versions also run under WOW64 on 64-bit systems. + + Visual Studio installs the 32-bit version of the CLR on an x86 computer, and both the 32-bit version and the appropriate 64-bit version of the CLR on a 64-bit Windows computer. (Because Visual Studio is a 32-bit application, when it is installed on a 64-bit system, it runs under WOW64.) - All applications that are built on the .NET Framework 1.0 or 1.1 are treated as 32-bit applications on a 64-bit operating system and are always executed under WOW64 and the 32-bit common language runtime (CLR). 32-bit applications that are built on the .NET Framework 4 or later versions also run under WOW64 on 64-bit systems. - - Visual Studio installs the 32-bit version of the CLR on an x86 computer, and both the 32-bit version and the appropriate 64-bit version of the CLR on a 64-bit Windows computer. (Because Visual Studio is a 32-bit application, when it is installed on a 64-bit system, it runs under WOW64.) - > [!NOTE] -> Because of the design of x86 emulation and the WOW64 subsystem for the Itanium processor family, applications are restricted to execution on one processor. These factors reduce the performance and scalability of 32-bit .NET Framework applications that run on Itanium-based systems. We recommend that you use the .NET Framework 4, which includes native 64-bit support for Itanium-based systems, for increased performance and scalability. - - By default, when you run a 64-bit managed application on a 64-bit Windows operating system, you can create an object of no more than 2 gigabytes (GB). However, in .NET Framework 4.5, you can increase this limit. For more information, see the [\ element](./configure-apps/file-schema/runtime/gcallowverylargeobjects-element.md). - - Many assemblies run identically on both the 32-bit CLR and the 64-bit CLR. However, some programs may behave differently, depending on the CLR, if they contain one or more of the following: - -- Structures that contain members that change size depending on the platform (for example, any pointer type). - -- Pointer arithmetic that includes constant sizes. - -- Incorrect platform invoke or COM declarations that use `Int32` for handles instead of `IntPtr`. - -- Code that casts `IntPtr` to `Int32`. - - For more information about how to port a 32-bit application to run on the 64-bit CLR, see [Migrating 32-bit Managed Code to 64-bit](/previous-versions/dotnet/articles/ms973190(v=msdn.10)). - -## General 64-Bit Programming Information - - For general information about 64-bit programming, see the following documents: - -- In the Windows SDK documentation, see [Programming Guide for 64-bit Windows](/windows/win32/winprog64/programming-guide-for-64-bit-windows). - -- For information about Visual Studio support for creating 64-bit applications, see [Visual Studio IDE 64-Bit Support](/visualstudio/ide/visual-studio-ide-64-bit-support). - -## Compiler Support for Creating 64-Bit Applications - - By default, when you use the .NET Framework to build an application on either a 32-bit or a 64-bit computer, the application will run on a 64-bit computer as a native application (that is, not under WOW64). The following table lists documents that explain how to use Visual Studio compilers to create 64-bit applications that will run as native, under WOW64, or both. - -|Compiler|Compiler option| -|--------------|---------------------| -|Visual Basic|[-platform (Visual Basic)](../visual-basic/reference/command-line-compiler/platform.md)| -|Visual C#|[-platform (C# Compiler Options)](../csharp/language-reference/compiler-options/output.md#platformtarget)| -|Visual C++|You can create platform-agnostic, Microsoft intermediate language (MSIL) applications by using **/clr:safe**. For more information, see [-clr (Common Language Runtime Compilation)](/cpp/build/reference/clr-common-language-runtime-compilation).

Visual C++ includes a separate compiler for each 64-bit operating system. For more information about how to use Visual C++ to create native applications that run on a 64-bit Windows operating system, see [64-bit Programming](/cpp/build/configuring-programs-for-64-bit-visual-cpp).| - -## Determining the Status of an .exe File or .dll File - - To determine whether an .exe file or .dll file is meant to run only on a specific platform or under WOW64, use [CorFlags.exe (CorFlags Conversion Tool)](./tools/corflags-exe-corflags-conversion-tool.md) with no options. You can also use CorFlags.exe to change the platform status of an .exe file or .dll file. The CLR header of a Visual Studio assembly has the major runtime version number set to 2 and the minor runtime version number set to 5. Applications that have the minor runtime version set to 0 are treated as legacy applications and are always executed under WOW64. - +> Because of the design of x86 emulation and the WOW64 subsystem for the Itanium processor family, applications are restricted to execution on one processor. These factors reduce the performance and scalability of 32-bit .NET Framework applications that run on Itanium-based systems. We recommend that you use the .NET Framework 4, which includes native 64-bit support for Itanium-based systems, for increased performance and scalability. + + By default, when you run a 64-bit managed application on a 64-bit Windows operating system, you can create an object of no more than 2 gigabytes (GB). However, in .NET Framework 4.5, you can increase this limit. For more information, see the [\ element](./configure-apps/file-schema/runtime/gcallowverylargeobjects-element.md). + + Many assemblies run identically on both the 32-bit CLR and the 64-bit CLR. However, some programs may behave differently, depending on the CLR, if they contain one or more of the following: + +- Structures that contain members that change size depending on the platform (for example, any pointer type). + +- Pointer arithmetic that includes constant sizes. + +- Incorrect platform invoke or COM declarations that use `Int32` for handles instead of `IntPtr`. + +- Code that casts `IntPtr` to `Int32`. + + For more information about how to port a 32-bit application to run on the 64-bit CLR, see [Migrating 32-bit Managed Code to 64-bit](/previous-versions/dotnet/articles/ms973190(v=msdn.10)). + +## General 64-Bit Programming Information + + For general information about 64-bit programming, see the following documents: + +- In the Windows SDK documentation, see [Programming Guide for 64-bit Windows](/windows/win32/winprog64/programming-guide-for-64-bit-windows). + +- For information about Visual Studio support for creating 64-bit applications, see [Visual Studio IDE 64-Bit Support](/visualstudio/ide/visual-studio-ide-64-bit-support). + +## Compiler Support for Creating 64-Bit Applications + + By default, when you use the .NET Framework to build an application on either a 32-bit or a 64-bit computer, the application will run on a 64-bit computer as a native application (that is, not under WOW64). The following table lists documents that explain how to use Visual Studio compilers to create 64-bit applications that will run as native, under WOW64, or both. + +|Compiler|Compiler option| +|--------------|---------------------| +|Visual Basic|[-platform (Visual Basic)](../visual-basic/reference/command-line-compiler/platform.md)| +|Visual C#|[-platform (C# Compiler Options)](../csharp/language-reference/compiler-options/output.md#platformtarget)| +|Visual C++|You can create platform-agnostic, common intermediate language (CIL) applications by using **/clr:safe**. For more information, see [-clr (Common Language Runtime Compilation)](/cpp/build/reference/clr-common-language-runtime-compilation).

Visual C++ includes a separate compiler for each 64-bit operating system. For more information about how to use Visual C++ to create native applications that run on a 64-bit Windows operating system, see [64-bit Programming](/cpp/build/configuring-programs-for-64-bit-visual-cpp).| + +## Determining the Status of an .exe File or .dll File + + To determine whether an .exe file or .dll file is meant to run only on a specific platform or under WOW64, use [CorFlags.exe (CorFlags Conversion Tool)](./tools/corflags-exe-corflags-conversion-tool.md) with no options. You can also use CorFlags.exe to change the platform status of an .exe file or .dll file. The CLR header of a Visual Studio assembly has the major runtime version number set to 2 and the minor runtime version number set to 5. Applications that have the minor runtime version set to 0 are treated as legacy applications and are always executed under WOW64. + To programmatically query an .exe or .dll to see whether it is meant to run only on a specific platform or under WOW64, use the method. diff --git a/docs/framework/app-domains/build-multifile-assembly.md b/docs/framework/app-domains/build-multifile-assembly.md index 38281dbd59713..d0168cb754e87 100644 --- a/docs/framework/app-domains/build-multifile-assembly.md +++ b/docs/framework/app-domains/build-multifile-assembly.md @@ -215,7 +215,7 @@ This article explains how to create a multifile assembly and provides code that al Client.netmodule Stringer.netmodule /main:MainClientApp.Main /out:myAssembly.exe /target:exe ``` - You can use the [MSIL Disassembler (Ildasm.exe)](../tools/ildasm-exe-il-disassembler.md) to examine the contents of an assembly, or determine whether a file is an assembly or a module. + You can use [IL Disassembler (Ildasm.exe)](../tools/ildasm-exe-il-disassembler.md) to examine the contents of an assembly, or determine whether a file is an assembly or a module. ## See also diff --git a/docs/framework/app-domains/working-with-assemblies-and-the-gac.md b/docs/framework/app-domains/working-with-assemblies-and-the-gac.md index 75742240fcca1..d9b12e27bd732 100644 --- a/docs/framework/app-domains/working-with-assemblies-and-the-gac.md +++ b/docs/framework/app-domains/working-with-assemblies-and-the-gac.md @@ -2,7 +2,7 @@ title: "Working with Assemblies and the Global Assembly Cache" description: Work with assemblies and the global assembly cache (GAC) in .NET. Review the reasons why you might want to install an assembly in the GAC. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "assemblies [.NET Framework], global assembly cache" - "global assembly cache, benefits" - "ACLs [.NET Framework]" @@ -12,60 +12,60 @@ ms.assetid: 8a18e5c2-d41d-49ef-abcb-7c27e2469433 --- # Working with Assemblies and the Global Assembly Cache -If you intend to share an assembly among several applications, you can install it into the global assembly cache. Each computer where the common language runtime is installed has this machine-wide code cache. The global assembly cache stores assemblies specifically designated to be shared by several applications on the computer. An assembly must have a strong name to be installed in the global assembly cache. - +If you intend to share an assembly among several applications, you can install it into the global assembly cache. Each computer where the common language runtime is installed has this machine-wide code cache. The global assembly cache stores assemblies specifically designated to be shared by several applications on the computer. An assembly must have a strong name to be installed in the global assembly cache. + > [!NOTE] -> Assemblies placed in the global assembly cache must have the same assembly name and file name (not including the file name extension). For example, an assembly with the assembly name of myAssembly must have a file name of either myAssembly.exe or myAssembly.dll. - -You should share assemblies by installing them into the global assembly cache only when necessary. As a general guideline, keep assembly dependencies private and locate assemblies in the application directory unless sharing an assembly is explicitly required. In addition, you do not have to install assemblies into the global assembly cache to make them accessible to COM interop or unmanaged code. - -There are several reasons why you might want to install an assembly into the global assembly cache: - -- Shared location. - - Assemblies that should be used by applications can be put in the global assembly cache. For example, if all applications should use an assembly located in the global assembly cache, a version policy statement can be added to the Machine.config file that redirects references to the assembly. - -- File security. - - Administrators often protect the systemroot directory using an Access Control List (ACL) to control write and execute access. Because the global assembly cache is installed in the systemroot directory, it inherits that directory's ACL. It is recommended that only users with Administrator privileges be allowed to delete files from the global assembly cache. - -- Side-by-side versioning. - - Multiple copies of assemblies with the same name but different version information can be maintained in the global assembly cache. - -- Additional search location. - - The common language runtime checks the global assembly cache for an assembly that matches the assembly request before probing or using the codebase information in a configuration file. - - Note that there are scenarios where you explicitly do not want to install an assembly into the global assembly cache. If you place one of the assemblies that make up an application into the global assembly cache, you can no longer replicate or install the application by using XCOPY to copy the application directory. In this case, you must also move the assembly into the global assembly cache. - -## In This Section - -[How to: Install an Assembly into the Global Assembly Cache](install-assembly-into-gac.md) -Describes the ways to install an assembly into the global assembly cache. - -[How to: View the Contents of the Global Assembly Cache](how-to-view-the-contents-of-the-gac.md) -Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to view the contents of the global assembly cache. - -[How to: Remove an Assembly from the Global Assembly Cache](how-to-remove-an-assembly-from-the-gac.md) -Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to remove an assembly from the global assembly cache. - -[Using Serviced Components with the Global Assembly Cache](use-serviced-components-with-the-gac.md) -Explains why serviced components (managed COM+ components) should be placed in the global assembly cache. - -## Related Sections - -[Creating Assemblies](../../standard/assembly/create.md) -Provides an overview of creating assemblies. - -[Global Assembly Cache](gac.md) -Describes the global assembly cache. - -[How to: View Assembly Contents](../../standard/assembly/view-contents.md) -Explains how to use the [Ildasm.exe (IL Disassembler)](../tools/ildasm-exe-il-disassembler.md) to view Microsoft intermediate language (MSIL) information in an assembly. - -[How the Runtime Locates Assemblies](../deployment/how-the-runtime-locates-assemblies.md) -Describes how the common language runtime locates and loads the assemblies that make up your application. - -[Programming with Assemblies](../../standard/assembly/index.md) +> Assemblies placed in the global assembly cache must have the same assembly name and file name (not including the file name extension). For example, an assembly with the assembly name of myAssembly must have a file name of either myAssembly.exe or myAssembly.dll. + +You should share assemblies by installing them into the global assembly cache only when necessary. As a general guideline, keep assembly dependencies private and locate assemblies in the application directory unless sharing an assembly is explicitly required. In addition, you do not have to install assemblies into the global assembly cache to make them accessible to COM interop or unmanaged code. + +There are several reasons why you might want to install an assembly into the global assembly cache: + +- Shared location. + + Assemblies that should be used by applications can be put in the global assembly cache. For example, if all applications should use an assembly located in the global assembly cache, a version policy statement can be added to the Machine.config file that redirects references to the assembly. + +- File security. + + Administrators often protect the systemroot directory using an Access Control List (ACL) to control write and execute access. Because the global assembly cache is installed in the systemroot directory, it inherits that directory's ACL. It is recommended that only users with Administrator privileges be allowed to delete files from the global assembly cache. + +- Side-by-side versioning. + + Multiple copies of assemblies with the same name but different version information can be maintained in the global assembly cache. + +- Additional search location. + + The common language runtime checks the global assembly cache for an assembly that matches the assembly request before probing or using the codebase information in a configuration file. + + Note that there are scenarios where you explicitly do not want to install an assembly into the global assembly cache. If you place one of the assemblies that make up an application into the global assembly cache, you can no longer replicate or install the application by using XCOPY to copy the application directory. In this case, you must also move the assembly into the global assembly cache. + +## In This Section + +[How to: Install an Assembly into the Global Assembly Cache](install-assembly-into-gac.md) +Describes the ways to install an assembly into the global assembly cache. + +[How to: View the Contents of the Global Assembly Cache](how-to-view-the-contents-of-the-gac.md) +Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to view the contents of the global assembly cache. + +[How to: Remove an Assembly from the Global Assembly Cache](how-to-remove-an-assembly-from-the-gac.md) +Explains how to use the [Gacutil.exe (Global Assembly Cache Tool)](../tools/gacutil-exe-gac-tool.md) to remove an assembly from the global assembly cache. + +[Using Serviced Components with the Global Assembly Cache](use-serviced-components-with-the-gac.md) +Explains why serviced components (managed COM+ components) should be placed in the global assembly cache. + +## Related Sections + +[Creating Assemblies](../../standard/assembly/create.md) +Provides an overview of creating assemblies. + +[Global Assembly Cache](gac.md) +Describes the global assembly cache. + +[How to: View Assembly Contents](../../standard/assembly/view-contents.md) +Explains how to use the [Ildasm.exe (IL Disassembler)](../tools/ildasm-exe-il-disassembler.md) to view common intermediate language (CIL) information in an assembly. + +[How the Runtime Locates Assemblies](../deployment/how-the-runtime-locates-assemblies.md) +Describes how the common language runtime locates and loads the assemblies that make up your application. + +[Programming with Assemblies](../../standard/assembly/index.md) Describes assemblies, the building blocks of managed applications. diff --git a/docs/framework/data/adonet/ef/language-reference/query-execution.md b/docs/framework/data/adonet/ef/language-reference/query-execution.md index 592a517f3fc80..bcead9dea7ee7 100644 --- a/docs/framework/data/adonet/ef/language-reference/query-execution.md +++ b/docs/framework/data/adonet/ef/language-reference/query-execution.md @@ -16,7 +16,7 @@ After a LINQ query is created by a user, it is converted to a command tree. A co When a LINQ to Entities query is executed, some expressions in the query might be executed on the server and some parts might be executed locally on the client. Client-side evaluation of an expression takes place before the query is executed on the server. If an expression is evaluated on the client, the result of that evaluation is substituted for the expression in the query, and the query is then executed on the server. Because queries are executed on the data source, the data source configuration overrides the behavior specified in the client. For example, null value handling and numerical precision depend on the server settings. Any exceptions thrown during query execution on the server are passed directly up to the client. > [!TIP] -> For a convenient summary of query operators in table format, which lets you quickly identify an operator's execution behavior, see [Classification of Standard Query Operators by Manner of Execution (C#)](../../../../../csharp/linq/query-a-collection-of-objects.md). +> For a convenient summary of query operators in table format, which lets you quickly identify an operator's execution behavior, see [Classification of Standard Query Operators by Manner of Execution (C#)](../../../../../csharp/linq/get-started/introduction-to-linq-queries.md). ## Deferred query execution diff --git a/docs/framework/data/adonet/protecting-connection-information.md b/docs/framework/data/adonet/protecting-connection-information.md index 857fe79b25c1d..20370268dc431 100644 --- a/docs/framework/data/adonet/protecting-connection-information.md +++ b/docs/framework/data/adonet/protecting-connection-information.md @@ -6,40 +6,40 @@ ms.assetid: 1471f580-bcd4-4046-bdaf-d2541ecda2f4 --- # Protecting Connection Information -Protecting access to your data source is one of the most important goals when securing an application. A connection string presents a potential vulnerability if it is not secured. Storing connection information in plain text or persisting it in memory risks compromising your entire system. Connection strings embedded in your source code can be read using the [Ildasm.exe (IL Disassembler)](../../tools/ildasm-exe-il-disassembler.md) to view Microsoft intermediate language (MSIL) in a compiled assembly. - - Security vulnerabilities involving connection strings can arise based on the type of authentication used, how connection strings are persisted in memory and on disk, and the techniques used to construct them at run time. - -## Use Windows Authentication - - To help limit access to your data source, you must secure connection information such as user ID, password, and data source name. In order to avoid exposing user information, we recommend using Windows authentication (sometimes referred to as *integrated security*) wherever possible. Windows authentication is specified in a connection string by using the `Integrated Security` or `Trusted_Connection` keywords, eliminating the need to use a user ID and password. When using Windows authentication, users are authenticated by Windows, and access to server and database resources is determined by granting permissions to Windows users and groups. - - For situations where it is not possible to use Windows authentication, you must use extra care because user credentials are exposed in the connection string. In an ASP.NET application, you can configure a Windows account as a fixed identity that is used to connect to databases and other network resources. You enable impersonation in the identity element in the **web.config** file and specify a user name and password. - -```xml +Protecting access to your data source is one of the most important goals when securing an application. A connection string presents a potential vulnerability if it is not secured. Storing connection information in plain text or persisting it in memory risks compromising your entire system. Connection strings embedded in your source code can be read using the [Ildasm.exe (IL Disassembler)](../../tools/ildasm-exe-il-disassembler.md) to view common intermediate language (CIL) in a compiled assembly. + + Security vulnerabilities involving connection strings can arise based on the type of authentication used, how connection strings are persisted in memory and on disk, and the techniques used to construct them at run time. + +## Use Windows Authentication + + To help limit access to your data source, you must secure connection information such as user ID, password, and data source name. In order to avoid exposing user information, we recommend using Windows authentication (sometimes referred to as *integrated security*) wherever possible. Windows authentication is specified in a connection string by using the `Integrated Security` or `Trusted_Connection` keywords, eliminating the need to use a user ID and password. When using Windows authentication, users are authenticated by Windows, and access to server and database resources is determined by granting permissions to Windows users and groups. + + For situations where it is not possible to use Windows authentication, you must use extra care because user credentials are exposed in the connection string. In an ASP.NET application, you can configure a Windows account as a fixed identity that is used to connect to databases and other network resources. You enable impersonation in the identity element in the **web.config** file and specify a user name and password. + +```xml -``` - - The fixed identity account should be a low-privilege account that has been granted only necessary permissions in the database. In addition, you should encrypt the configuration file so that the user name and password are not exposed in clear text. - -## Do Not Use Universal Data Link (UDL) files - - Avoid storing connection strings for an in a Universal Data Link (UDL) file. UDLs are stored in clear text and cannot be encrypted. A UDL file is an external file-based resource to your application, and it cannot be secured or encrypted using the .NET Framework. - -## Avoid Injection Attacks with Connection String Builders - - A connection string injection attack can occur when dynamic string concatenation is used to build connection strings based on user input. If the user input is not validated and malicious text or characters not escaped, an attacker can potentially access sensitive data or other resources on the server. To address this problem, ADO.NET 2.0 introduced new connection string builder classes to validate connection string syntax and ensure that additional parameters are not introduced. For more information, see [Connection String Builders](connection-string-builders.md). - -## Use Persist Security Info=False - - The default value for `Persist Security Info` is false; we recommend using this default in all connection strings. Setting `Persist Security Info` to `true` or `yes` allows security-sensitive information, including the user ID and password, to be obtained from a connection after it has been opened. When `Persist Security Info` is set to `false` or `no`, security information is discarded after it is used to open the connection, ensuring that an untrusted source does not have access to security-sensitive information. - -## Encrypt Configuration Files - - You can also store connection strings in configuration files, which eliminates the need to embed them in your application's code. Configuration files are standard XML files for which the .NET Framework has defined a common set of elements. Connection strings in configuration files are typically stored inside the **\** element in the **app.config** for a Windows application, or the **web.config** file for an ASP.NET application. For more information on the basics of storing, retrieving and encrypting connection strings from configuration files, see [Connection Strings and Configuration Files](connection-strings-and-configuration-files.md). - + password="*****" /> +``` + + The fixed identity account should be a low-privilege account that has been granted only necessary permissions in the database. In addition, you should encrypt the configuration file so that the user name and password are not exposed in clear text. + +## Do Not Use Universal Data Link (UDL) files + + Avoid storing connection strings for an in a Universal Data Link (UDL) file. UDLs are stored in clear text and cannot be encrypted. A UDL file is an external file-based resource to your application, and it cannot be secured or encrypted using the .NET Framework. + +## Avoid Injection Attacks with Connection String Builders + + A connection string injection attack can occur when dynamic string concatenation is used to build connection strings based on user input. If the user input is not validated and malicious text or characters not escaped, an attacker can potentially access sensitive data or other resources on the server. To address this problem, ADO.NET 2.0 introduced new connection string builder classes to validate connection string syntax and ensure that additional parameters are not introduced. For more information, see [Connection String Builders](connection-string-builders.md). + +## Use Persist Security Info=False + + The default value for `Persist Security Info` is false; we recommend using this default in all connection strings. Setting `Persist Security Info` to `true` or `yes` allows security-sensitive information, including the user ID and password, to be obtained from a connection after it has been opened. When `Persist Security Info` is set to `false` or `no`, security information is discarded after it is used to open the connection, ensuring that an untrusted source does not have access to security-sensitive information. + +## Encrypt Configuration Files + + You can also store connection strings in configuration files, which eliminates the need to embed them in your application's code. Configuration files are standard XML files for which the .NET Framework has defined a common set of elements. Connection strings in configuration files are typically stored inside the **\** element in the **app.config** for a Windows application, or the **web.config** file for an ASP.NET application. For more information on the basics of storing, retrieving and encrypting connection strings from configuration files, see [Connection Strings and Configuration Files](connection-strings-and-configuration-files.md). + ## See also - [Securing ADO.NET Applications](securing-ado-net-applications.md) diff --git a/docs/framework/debug-trace-profile/code-contracts.md b/docs/framework/debug-trace-profile/code-contracts.md index d75aaa749b383..48ef0d8a7176b 100644 --- a/docs/framework/debug-trace-profile/code-contracts.md +++ b/docs/framework/debug-trace-profile/code-contracts.md @@ -29,7 +29,7 @@ The benefits of code contracts include the following: - Reference documentation: The documentation generator augments existing XML documentation files with contract information. There are also style sheets that can be used with [Sandcastle](https://github.com/EWSoftware/SHFB) so that the generated documentation pages have contract sections. -All .NET Framework languages can immediately take advantage of contracts; you do not have to write a special parser or compiler. A Visual Studio add-in lets you specify the level of code contract analysis to be performed. The analyzers can confirm that the contracts are well-formed (type checking and name resolution) and can produce a compiled form of the contracts in Microsoft intermediate language (MSIL) format. Authoring contracts in Visual Studio lets you take advantage of the standard IntelliSense provided by the tool. +All .NET Framework languages can immediately take advantage of contracts; you do not have to write a special parser or compiler. A Visual Studio add-in lets you specify the level of code contract analysis to be performed. The analyzers can confirm that the contracts are well-formed (type checking and name resolution) and can produce a compiled form of the contracts in common intermediate language (CIL) format. Authoring contracts in Visual Studio lets you take advantage of the standard IntelliSense provided by the tool. Most methods in the contract class are conditionally compiled; that is, the compiler emits calls to these methods only when you define a special symbol, CONTRACTS_FULL, by using the `#define` directive. CONTRACTS_FULL lets you write contracts in your code without using `#ifdef` directives; you can produce different builds, some with contracts, and some without. diff --git a/docs/framework/debug-trace-profile/index.md b/docs/framework/debug-trace-profile/index.md index ffb77c4711a62..85d24f3c1c6a1 100644 --- a/docs/framework/debug-trace-profile/index.md +++ b/docs/framework/debug-trace-profile/index.md @@ -2,7 +2,7 @@ title: "Debugging, Tracing, and Profiling" description: Read about debugging, tracing, and profiling in .NET. See articles covering just-in-time (JIT) debugging, tracing and instrumenting applications, and more. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "debugging [.NET Framework]" - ".NET Framework application configuration, debugging" - "debugging [.NET Framework], .NET Framework application debugging" @@ -17,24 +17,24 @@ ms.assetid: 4a04863e-2475-46f4-bc3f-3c11510c2a4b --- # Debugging, tracing, and profiling -To debug a .NET Framework application, the compiler and runtime environment must be configured to enable a debugger to attach to the application and to produce both symbols and line maps, if possible, for the application and its corresponding Microsoft intermediate language (MSIL). After a managed application has been debugged, it can be profiled to boost performance. Profiling evaluates and describes the lines of source code that generate the most frequently executed code, and how much time it takes to execute them. - - .NET Framework applications are easily debugged by using Visual Studio, which handles many of the configuration details. If Visual Studio is not installed, you can examine and improve the performance of .NET Framework applications by using the debugging classes in the .NET Framework namespace. This namespace includes the , , and classes for tracing execution flow, and the , , and classes for profiling code. - -## In this section +To debug a .NET Framework application, the compiler and runtime environment must be configured to enable a debugger to attach to the application and to produce both symbols and line maps, if possible, for the application and its corresponding common intermediate language (CIL). After a managed application has been debugged, it can be profiled to boost performance. Profiling evaluates and describes the lines of source code that generate the most frequently executed code, and how much time it takes to execute them. + + .NET Framework applications are easily debugged by using Visual Studio, which handles many of the configuration details. If Visual Studio is not installed, you can examine and improve the performance of .NET Framework applications by using the debugging classes in the .NET Framework namespace. This namespace includes the , , and classes for tracing execution flow, and the , , and classes for profiling code. + +## In this section [Enabling JIT-Attach Debugging](enabling-jit-attach-debugging.md)\ -Shows how to configure the registry to JIT-attach a debug engine to a .NET Framework application. - +Shows how to configure the registry to JIT-attach a debug engine to a .NET Framework application. + [Making an Image Easier to Debug](making-an-image-easier-to-debug.md)\ -Shows how to turn JIT tracking on and optimization off to make an assembly easier to debug. - +Shows how to turn JIT tracking on and optimization off to make an assembly easier to debug. + [Tracing and Instrumenting Applications](tracing-and-instrumenting-applications.md)\ -Describes how to monitor the execution of your application while it is running, and how to instrument it to display how well it is performing or whether something has gone wrong. - +Describes how to monitor the execution of your application while it is running, and how to instrument it to display how well it is performing or whether something has gone wrong. + [Diagnosing Errors with Managed Debugging Assistants](diagnosing-errors-with-managed-debugging-assistants.md)\ -Describes managed debugging assistants (MDAs), which are debugging aids that work in conjunction with the common language runtime (CLR) to provide information on runtime state. - +Describes managed debugging assistants (MDAs), which are debugging aids that work in conjunction with the common language runtime (CLR) to provide information on runtime state. + [Enhancing Debugging with the Debugger Display Attributes](enhancing-debugging-with-the-debugger-display-attributes.md)\ Describes how the developer of a type can specify what that type will look like when it is displayed in a debugger. @@ -42,12 +42,12 @@ Describes how the developer of a type can specify what that type will look like Learn how to gather information about application performance. [Performance Counters](performance-counters.md)\ -Describes the counters that you can use to track the performance of an application. - -## Related sections - -[Debug ASP.NET or ASP.NET Core apps in Visual Studio](/visualstudio/debugger/how-to-enable-debugging-for-aspnet-applications) -Provides prerequisites and instructions for how to debug an ASP.NET application during development or after deployment. - -[Development Guide](../development-guide.md) +Describes the counters that you can use to track the performance of an application. + +## Related sections + +[Debug ASP.NET or ASP.NET Core apps in Visual Studio](/visualstudio/debugger/how-to-enable-debugging-for-aspnet-applications) +Provides prerequisites and instructions for how to debug an ASP.NET application during development or after deployment. + +[Development Guide](../development-guide.md) Provides a guide to all key technology areas and tasks for application development, including creating, configuring, debugging, securing, and deploying your application, and information about dynamic programming, interoperability, extensibility, memory management, and threading. diff --git a/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md b/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md index e2a5c3efa3b45..76480957db375 100644 --- a/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md +++ b/docs/framework/debug-trace-profile/making-an-image-easier-to-debug.md @@ -13,15 +13,15 @@ ms.assetid: 7d90ea7a-150f-4f97-98a7-f9c26541b9a3 When compiling unmanaged code, you can configure an executable image for debugging by setting IDE switches or command-line options. For example, you can use the /**Zi** command-line option in Visual C++ to ask it to emit debug symbol files (file extension .pdb). Similarly, the /**Od** command-line option tells the compiler to disable optimization. The resulting code runs more slowly, but it's easier to debug, should this be necessary. -When compiling .NET Framework managed code, compilers such as Visual C++, Visual Basic, and C# compile their source program into Microsoft intermediate language (MSIL). MSIL is then JIT-compiled, just before execution, into native machine code. As with unmanaged code, you can configure an executable image for debugging by setting IDE switches or command-line options. You can also configure the JIT compilation for debugging in much the same way. +When compiling .NET Framework managed code, compilers such as Visual C++, Visual Basic, and C# compile their source program into common intermediate language (CIL). CIL is then JIT-compiled, just before execution, into native machine code. As with unmanaged code, you can configure an executable image for debugging by setting IDE switches or command-line options. You can also configure the JIT compilation for debugging in much the same way. This JIT configuration has two aspects: -- You can request the JIT compiler to generate tracking information. This makes it possible for the debugger to match up a chain of MSIL with its machine code counterpart, and to track where local variables and function arguments are stored. In .NET Framework version 2.0 and later, the JIT compiler always generates tracking information, so there's no need to request it. +- You can request the JIT compiler to generate tracking information. This makes it possible for the debugger to match up a chain of CIL with its machine code counterpart, and to track where local variables and function arguments are stored. In .NET Framework version 2.0 and later, the JIT compiler always generates tracking information, so there's no need to request it. - You can request the JIT compiler to not optimize the resulting machine code. -Normally, the compiler that generates the MSIL sets these JIT compiler options appropriately, based upon the IDE switches or command-line options you specify, for example, /**Od**. +Normally, the compiler that generates the CIL sets these JIT compiler options appropriately, based upon the IDE switches or command-line options you specify, for example, /**Od**. In some cases, you might want to change the behavior of the JIT compiler so that the machine code it generates is easier to debug. For example, you might want to generate JIT tracking information for a retail build or control optimization. You can do so with an initialization (.ini) file. diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index 3b456a7b83fb8..4ab462a627fab 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -43,12 +43,12 @@ The *.NET CLR JIT* category includes counters that provide information about cod |Performance counter|Description| |-------------------------|-----------------| -|**# of IL Bytes JITted**|Displays the total number of Microsoft intermediate language (MSIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| +|**# of IL Bytes JITted**|Displays the total number of common intermediate language (CIL) bytes compiled by the just-in-time (JIT) compiler since the application started. This counter is equivalent to the **Total # of IL Bytes Jitted** counter.| |**# of Methods JITted**|Displays the total number of methods JIT-compiled since the application started. This counter does not include pre-JIT-compiled methods.| |**% Time in Jit**|Displays the percentage of elapsed time spent in JIT compilation since the last JIT compilation phase. This counter is updated at the end of every JIT compilation phase. A JIT compilation phase occurs when a method and its dependencies are compiled.| -|**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| -|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| -|**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| +|**IL Bytes Jitted / sec**|Displays the number of CIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| +|**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the CIL cannot be verified or if there is an internal error in the JIT compiler.| +|**Total # of IL Bytes Jitted**|Displays the total CIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| ## Loading performance counters diff --git a/docs/framework/install/on-windows-10.md b/docs/framework/install/on-windows-10.md index 16bbc30efc6ad..f312dc0049458 100644 --- a/docs/framework/install/on-windows-10.md +++ b/docs/framework/install/on-windows-10.md @@ -5,7 +5,7 @@ ms.date: 10/06/2021 --- # Install the .NET Framework on Windows 10 and Windows Server 2016 and later -The .NET Framework is required to run many applications on Windows. The instructions in this article should help you install the .NET Framework versions that you need. The [.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/master/releases/net48) is the latest available version. +The .NET Framework is required to run many applications on Windows. The instructions in this article should help you install the .NET Framework versions that you need. The [.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/main/releases/net48) is the latest available version. You may have arrived on this page after trying to run an application and seeing a dialog on your machine similar to the following one: diff --git a/docs/framework/install/on-windows-8-1.md b/docs/framework/install/on-windows-8-1.md index b5a2b9b3b84fe..b420df785928b 100644 --- a/docs/framework/install/on-windows-8-1.md +++ b/docs/framework/install/on-windows-8-1.md @@ -10,14 +10,14 @@ The .NET Framework is required to run many applications on Windows. You can use ![This application could not be started](./media/this-application-could-not-be-started.png) -These instructions will help you install the .NET Framework versions you need. [.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/master/releases/net48) is the latest version. It is supported on Windows 8.1 and Windows Server 2012 R2. It's included with Windows 11 and in Windows 10 starting with the [May 2019 Update](https://support.microsoft.com/help/4028685/windows-10-get-the-update). +These instructions will help you install the .NET Framework versions you need. [.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/main/releases/net48) is the latest version. It is supported on Windows 8.1 and Windows Server 2012 R2. It's included with Windows 11 and in Windows 10 starting with the [May 2019 Update](https://support.microsoft.com/help/4028685/windows-10-get-the-update). ## .NET Framework 4.8 > [!div class="button"] > [Download .NET Framework 4.8](https://dotnet.microsoft.com/download/dotnet-framework/net48) -[.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/master/releases/net48) can be used to run applications built for .NET Framework 4.0 or later. +[.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/main/releases/net48) can be used to run applications built for .NET Framework 4.0 or later. ## .NET Framework 3.5 diff --git a/docs/framework/install/on-windows-8.md b/docs/framework/install/on-windows-8.md index 39d3a14e8a03f..e48bbf9733e5a 100644 --- a/docs/framework/install/on-windows-8.md +++ b/docs/framework/install/on-windows-8.md @@ -10,7 +10,7 @@ The .NET Framework is required to run many applications on Windows. You can use ![This application could not be started](./media/this-application-could-not-be-started.png) -These instructions will help you install the .NET Framework versions you need. [.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/master/releases/net48) is the latest version. It is supported on Windows Server 2012 but is not supported on Windows 8. It's included with Windows 11 and in Windows 10 starting with the [May 2019 Update](https://support.microsoft.com/help/4028685/windows-10-get-the-update). +These instructions will help you install the .NET Framework versions you need. [.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/main/releases/net48) is the latest version. It is supported on Windows Server 2012 but is not supported on Windows 8. It's included with Windows 11 and in Windows 10 starting with the [May 2019 Update](https://support.microsoft.com/help/4028685/windows-10-get-the-update). ## .NET Framework 4.8 @@ -19,7 +19,7 @@ These instructions will help you install the .NET Framework versions you need. [ .NET Framework 4.8 is supported on Windows Server 2012. It is not supported on Windows 8. -[.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/master/releases/net48) can be used to run applications built for .NET Framework 4.0 or later. +[.NET Framework 4.8](https://github.com/Microsoft/dotnet/tree/main/releases/net48) can be used to run applications built for .NET Framework 4.0 or later. ## .NET Framework 4.6 diff --git a/docs/framework/interop/default-marshalling-for-arrays.md b/docs/framework/interop/default-marshalling-for-arrays.md index 0676ca8919027..0fc689d444efc 100644 --- a/docs/framework/interop/default-marshalling-for-arrays.md +++ b/docs/framework/interop/default-marshalling-for-arrays.md @@ -2,368 +2,368 @@ title: "Default Marshalling for Arrays" description: Understand default marshalling for arrays. Review managed arrays, unmanaged arrays, passing array parameters to .NET code, and passing arrays to COM. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "interop marshalling, arrays" - "arrays, interop marshalling" ms.assetid: 8a3cca8b-dd94-4e3d-ad9a-9ee7590654bc --- # Default Marshalling for Arrays -In an application consisting entirely of managed code, the common language runtime passes array types as In/Out parameters. In contrast, the interop marshaller passes an array as In parameters by default. - - With [pinning optimization](copying-and-pinning.md), a blittable array can appear to operate as an In/Out parameter when interacting with objects in the same apartment. However, if you later export the code to a type library used to generate the cross-machine proxy, and that library is used to marshal your calls across apartments, the calls can revert to true In parameter behavior. - - Arrays are complex by nature, and the distinctions between managed and unmanaged arrays warrant more information than other non-blittable types. - -## Managed Arrays - - Managed array types can vary; however, the class is the base class of all array types. The **System.Array** class has properties for determining the rank, length, and lower and upper bounds of an array, as well as methods for accessing, sorting, searching, copying, and creating arrays. - - These array types are dynamic and do not have a corresponding static type defined in the base class library. It is convenient to think of each combination of element type and rank as a distinct type of array. Therefore, a one-dimensional array of integers is of a different type than a one-dimensional array of double types. Similarly a two-dimensional array of integers is different from a one-dimensional array of integers. The bounds of the array are not considered when comparing types. - - As the following table shows, any instance of a managed array must be of a specific element type, rank, and lower bound. - -|Managed array type|Element type|Rank|Lower bound|Signature notation| -|------------------------|------------------|----------|-----------------|------------------------| -|**ELEMENT_TYPE_ARRAY**|Specified by type.|Specified by rank.|Optionally specified by bounds.|*type* **[** *n*,*m* **]**| -|**ELEMENT_TYPE_CLASS**|Unknown|Unknown|Unknown|**System.Array**| -|**ELEMENT_TYPE_SZARRAY**|Specified by type.|1|0|*type* **[** *n* **]**| - -## Unmanaged Arrays - - Unmanaged arrays are either COM-style safe arrays or C-style arrays with fixed or variable length. Safe arrays are self-describing arrays that carry the type, rank, and bounds of the associated array data. C-style arrays are one-dimensional typed arrays with a fixed lower bound of 0. The marshalling service has limited support for both types of arrays. - -## Passing Array Parameters to .NET Code - - Both C-style arrays and safe arrays can be passed to .NET code from unmanaged code as either a safe array or a C-style array. The following table shows the unmanaged type value and the imported type. - -|Unmanaged type|Imported type| -|--------------------|-------------------| -|**SafeArray(** *Type* **)**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature. Safe arrays that are not rank = 1 or lower bound = 0 cannot be marshalled as **SZARRAY**.| -|*Type* **[]**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature.| - -### Safe Arrays - - When a safe array is imported from a type library to a .NET assembly, the array is converted to a one-dimensional array of a known type (such as **int**). The same type conversion rules that apply to parameters also apply to array elements. For example, a safe array of **BSTR** types becomes a managed array of strings and a safe array of variants becomes a managed array of objects. The **SAFEARRAY** element type is captured from the type library and saved in the **SAFEARRAY** value of the enumeration. - - Because the rank and bounds of the safe array cannot be determined from the type library, the rank is assumed to equal 1 and the lower bound is assumed to equal 0. The rank and bounds must be defined in the managed signature produced by the [Type Library Importer (Tlbimp.exe)](../tools/tlbimp-exe-type-library-importer.md). If the rank passed to the method at run time differs, a is thrown. If the type of the array passed at run time differs, a is thrown. The following example shows safe arrays in managed and unmanaged code. - - **Unmanaged signature** - +In an application consisting entirely of managed code, the common language runtime passes array types as In/Out parameters. In contrast, the interop marshaller passes an array as In parameters by default. + + With [pinning optimization](copying-and-pinning.md), a blittable array can appear to operate as an In/Out parameter when interacting with objects in the same apartment. However, if you later export the code to a type library used to generate the cross-machine proxy, and that library is used to marshal your calls across apartments, the calls can revert to true In parameter behavior. + + Arrays are complex by nature, and the distinctions between managed and unmanaged arrays warrant more information than other non-blittable types. + +## Managed Arrays + + Managed array types can vary; however, the class is the base class of all array types. The **System.Array** class has properties for determining the rank, length, and lower and upper bounds of an array, as well as methods for accessing, sorting, searching, copying, and creating arrays. + + These array types are dynamic and do not have a corresponding static type defined in the base class library. It is convenient to think of each combination of element type and rank as a distinct type of array. Therefore, a one-dimensional array of integers is of a different type than a one-dimensional array of double types. Similarly a two-dimensional array of integers is different from a one-dimensional array of integers. The bounds of the array are not considered when comparing types. + + As the following table shows, any instance of a managed array must be of a specific element type, rank, and lower bound. + +|Managed array type|Element type|Rank|Lower bound|Signature notation| +|------------------------|------------------|----------|-----------------|------------------------| +|**ELEMENT_TYPE_ARRAY**|Specified by type.|Specified by rank.|Optionally specified by bounds.|*type* **[** *n*,*m* **]**| +|**ELEMENT_TYPE_CLASS**|Unknown|Unknown|Unknown|**System.Array**| +|**ELEMENT_TYPE_SZARRAY**|Specified by type.|1|0|*type* **[** *n* **]**| + +## Unmanaged Arrays + + Unmanaged arrays are either COM-style safe arrays or C-style arrays with fixed or variable length. Safe arrays are self-describing arrays that carry the type, rank, and bounds of the associated array data. C-style arrays are one-dimensional typed arrays with a fixed lower bound of 0. The marshalling service has limited support for both types of arrays. + +## Passing Array Parameters to .NET Code + + Both C-style arrays and safe arrays can be passed to .NET code from unmanaged code as either a safe array or a C-style array. The following table shows the unmanaged type value and the imported type. + +|Unmanaged type|Imported type| +|--------------------|-------------------| +|**SafeArray(** *Type* **)**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature. Safe arrays that are not rank = 1 or lower bound = 0 cannot be marshalled as **SZARRAY**.| +|*Type* **[]**|**ELEMENT_TYPE_SZARRAY** **\<** *ConvertedType* **>**

Rank = 1, lower bound = 0. Size is known only if provided in the managed signature.| + +### Safe Arrays + + When a safe array is imported from a type library to a .NET assembly, the array is converted to a one-dimensional array of a known type (such as **int**). The same type conversion rules that apply to parameters also apply to array elements. For example, a safe array of **BSTR** types becomes a managed array of strings and a safe array of variants becomes a managed array of objects. The **SAFEARRAY** element type is captured from the type library and saved in the **SAFEARRAY** value of the enumeration. + + Because the rank and bounds of the safe array cannot be determined from the type library, the rank is assumed to equal 1 and the lower bound is assumed to equal 0. The rank and bounds must be defined in the managed signature produced by the [Type Library Importer (Tlbimp.exe)](../tools/tlbimp-exe-type-library-importer.md). If the rank passed to the method at run time differs, a is thrown. If the type of the array passed at run time differs, a is thrown. The following example shows safe arrays in managed and unmanaged code. + + **Unmanaged signature** + ```cpp -HRESULT New1([in] SAFEARRAY( int ) ar); -HRESULT New2([in] SAFEARRAY( DATE ) ar); -HRESULT New3([in, out] SAFEARRAY( BSTR ) *ar); -``` - - **Managed signature** - -```vb -Sub New1( _ - ar() As Integer) +HRESULT New1([in] SAFEARRAY( int ) ar); +HRESULT New2([in] SAFEARRAY( DATE ) ar); +HRESULT New3([in, out] SAFEARRAY( BSTR ) *ar); +``` + + **Managed signature** + +```vb +Sub New1( _ + ar() As Integer) Sub New2( _ - ar() As DateTime) + ar() As DateTime) Sub New3(ByRef _ - ar() As String) -``` - -```csharp -void New1([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_I4)] int[] ar) ; + ar() As String) +``` + +```csharp +void New1([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_I4)] int[] ar) ; void New2([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_DATE)] - DateTime[] ar); + DateTime[] ar); void New3([MarshalAs(UnmanagedType.SafeArray, SafeArraySubType=VT_BSTR)] - ref String[] ar); -``` - - Multidimensional, or nonzero-bound safe arrays, can be marshalled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). - -### C-Style Arrays - - When a C-style array is imported from a type library to a .NET assembly, the array is converted to **ELEMENT_TYPE_SZARRAY**. - - The array element type is determined from the type library and preserved during the import. The same conversion rules that apply to parameters also apply to array elements. For example, an array of **LPStr** types becomes an array of **String** types. Tlbimp.exe captures the array element type and applies the attribute to the parameter. - - The array rank is assumed to equal 1. If the rank is greater than 1, the array is marshalled as a one-dimensional array in column-major order. The lower bound always equals 0. - - Type libraries can contain arrays of fixed or variable length. Tlbimp.exe can import only fixed-length arrays from type libraries because type libraries lack the information needed to marshal variable-length arrays. With fixed-length arrays, the size is imported from the type library and captured in the **MarshalAsAttribute** that is applied to the parameter. - - You must manually define type libraries containing variable-length arrays, as shown in the following example. - - **Unmanaged signature** - + ref String[] ar); +``` + + Multidimensional, or nonzero-bound safe arrays, can be marshalled into managed code if the method signature produced by Tlbimp.exe is modified to indicate an element type of **ELEMENT_TYPE_ARRAY** instead of **ELEMENT_TYPE_SZARRAY**. Alternatively, you can use the **/sysarray** switch with Tlbimp.exe to import all arrays as objects. In cases where the array being passed is known to be multidimensional, you can edit the common intermediate language (CIL) code produced by Tlbimp.exe and then recompile it. For details about how to modify CIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). + +### C-Style Arrays + + When a C-style array is imported from a type library to a .NET assembly, the array is converted to **ELEMENT_TYPE_SZARRAY**. + + The array element type is determined from the type library and preserved during the import. The same conversion rules that apply to parameters also apply to array elements. For example, an array of **LPStr** types becomes an array of **String** types. Tlbimp.exe captures the array element type and applies the attribute to the parameter. + + The array rank is assumed to equal 1. If the rank is greater than 1, the array is marshalled as a one-dimensional array in column-major order. The lower bound always equals 0. + + Type libraries can contain arrays of fixed or variable length. Tlbimp.exe can import only fixed-length arrays from type libraries because type libraries lack the information needed to marshal variable-length arrays. With fixed-length arrays, the size is imported from the type library and captured in the **MarshalAsAttribute** that is applied to the parameter. + + You must manually define type libraries containing variable-length arrays, as shown in the following example. + + **Unmanaged signature** + ```cpp -HRESULT New1(int ar[10]); -HRESULT New2(double ar[10][20]); -HRESULT New3(LPWStr ar[10]); -``` - - **Managed signature** - -```vb -Sub New1( _ - ar() As Integer) -Sub New2( _ - ar() As Double) -Sub New2( _ - ar() As String) -``` - -```csharp -void New1([MarshalAs(UnmanagedType.LPArray, SizeConst=10)] int[] ar); -void New2([MarshalAs(UnmanagedType.LPArray, SizeConst=200)] double[] ar); +HRESULT New1(int ar[10]); +HRESULT New2(double ar[10][20]); +HRESULT New3(LPWStr ar[10]); +``` + + **Managed signature** + +```vb +Sub New1( _ + ar() As Integer) +Sub New2( _ + ar() As Double) +Sub New2( _ + ar() As String) +``` + +```csharp +void New1([MarshalAs(UnmanagedType.LPArray, SizeConst=10)] int[] ar); +void New2([MarshalAs(UnmanagedType.LPArray, SizeConst=200)] double[] ar); void New2([MarshalAs(UnmanagedType.LPArray, - ArraySubType=UnmanagedType.LPWStr, SizeConst=10)] String[] ar); -``` - - Although you can apply the **size_is** or **length_is** attributes to an array in Interface Definition Language (IDL) source to convey the size to a client, the Microsoft Interface Definition Language (MIDL) compiler does not propagate that information to the type library. Without knowing the size, the interop marshalling service cannot marshal the array elements. Consequently, variable-length arrays are imported as reference arguments. For example: - - **Unmanaged signature** - + ArraySubType=UnmanagedType.LPWStr, SizeConst=10)] String[] ar); +``` + + Although you can apply the **size_is** or **length_is** attributes to an array in Interface Definition Language (IDL) source to convey the size to a client, the Microsoft Interface Definition Language (MIDL) compiler does not propagate that information to the type library. Without knowing the size, the interop marshalling service cannot marshal the array elements. Consequently, variable-length arrays are imported as reference arguments. For example: + + **Unmanaged signature** + ```cpp -HRESULT New1(int ar[]); -HRESULT New2(int ArSize, [size_is(ArSize)] double ar[]); -HRESULT New3(int ElemCnt, [length_is(ElemCnt)] LPStr ar[]); -``` - - **Managed signature** - -```vb -Sub New1(ByRef ar As Integer) -Sub New2(ByRef ar As Double) -Sub New3(ByRef ar As String) -``` - -```csharp +HRESULT New1(int ar[]); +HRESULT New2(int ArSize, [size_is(ArSize)] double ar[]); +HRESULT New3(int ElemCnt, [length_is(ElemCnt)] LPStr ar[]); +``` + + **Managed signature** + +```vb +Sub New1(ByRef ar As Integer) +Sub New2(ByRef ar As Double) +Sub New3(ByRef ar As String) +``` + +```csharp void New1(ref int ar); void New2(ref double ar); void New3(ref String ar); -``` - - You can provide the marshaller with the array size by editing the Microsoft intermediate language (MSIL) code produced by Tlbimp.exe and then recompiling it. For details about how to modify MSIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). To indicate the number of elements in the array, apply the type to the array parameter of the managed method definition in one of the following ways: - +``` + + You can provide the marshaller with the array size by editing the common intermediate language (CIL) code produced by Tlbimp.exe and then recompiling it. For details about how to modify CIL code, see [Customizing Runtime Callable Wrappers](/previous-versions/dotnet/netframework-4.0/e753eftz(v=vs.100)). To indicate the number of elements in the array, apply the type to the array parameter of the managed method definition in one of the following ways: + - Identify another parameter that contains the number of elements in the array. The parameters are identified by position, starting with the first parameter as number 0. - - ```vb - Sub [New](ElemCnt As Integer, _ - \ _ - ar() As Integer) - ``` - - ```csharp - void New( + + ```vb + Sub [New](ElemCnt As Integer, _ + \ _ + ar() As Integer) + ``` + + ```csharp + void New( int ElemCnt, - [MarshalAs(UnmanagedType.LPArray, SizeParamIndex=0)] int[] ar ); - ``` - -- Define the size of the array as a constant. For example: - - ```vb - Sub [New](\ _ - ar() As Integer) - ``` - - ```csharp - void New( - [MarshalAs(UnmanagedType.LPArray, SizeConst=128)] int[] ar ); - ``` - - When marshalling arrays from unmanaged code to managed code, the marshaller checks the **MarshalAsAttribute** associated with the parameter to determine the array size. If the array size is not specified, only one element is marshalled. - + [MarshalAs(UnmanagedType.LPArray, SizeParamIndex=0)] int[] ar ); + ``` + +- Define the size of the array as a constant. For example: + + ```vb + Sub [New](\ _ + ar() As Integer) + ``` + + ```csharp + void New( + [MarshalAs(UnmanagedType.LPArray, SizeConst=128)] int[] ar ); + ``` + + When marshalling arrays from unmanaged code to managed code, the marshaller checks the **MarshalAsAttribute** associated with the parameter to determine the array size. If the array size is not specified, only one element is marshalled. + > [!NOTE] -> The **MarshalAsAttribute** has no effect on marshalling managed arrays to unmanaged code. In that direction, the array size is determined by examination. There is no way to marshal a subset of a managed array. - - The interop marshaller uses the **CoTaskMemAlloc** and **CoTaskMemFree** methods on Windows or **malloc** and **free** methods on other operating systems to allocate and retrieve memory. Memory allocation performed by unmanaged code must also use these methods. - -## Passing Arrays to COM - - All managed array types can be passed to unmanaged code from managed code. Depending on the managed type and the attributes applied to it, the array can be accessed as a safe array or a C-style array, as shown in the following table. - -|Managed array type|Exported as| -|------------------------|-----------------| -|**ELEMENT_TYPE_SZARRAY** **\<** *type* **>**| **.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type is provided in the signature. Rank is always 1, lower bound is always 0. Size is always known at run time.| -|**ELEMENT_TYPE_ARRAY** **\<** *type* **>** **\<** *rank* **>**[**\<** *bounds* **>**]|**UnmanagedType.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type, rank, bounds are provided in the signature. Size is always known at run time.| -|**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| - - There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshalled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. - -### ELEMENT_TYPE_SZARRAY - - When a method containing an **ELEMENT_TYPE_SZARRAY** parameter (one-dimensional array) is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The same conversion rules apply to the array element types. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: - -#### Managed signature - -```vb -Sub [New](ar() As Long) -Sub [New](ar() As String) -``` - -```csharp -void New(long[] ar ); -void New(String[] ar ); -``` - -#### Unmanaged signature - +> The **MarshalAsAttribute** has no effect on marshalling managed arrays to unmanaged code. In that direction, the array size is determined by examination. There is no way to marshal a subset of a managed array. + + The interop marshaller uses the **CoTaskMemAlloc** and **CoTaskMemFree** methods on Windows or **malloc** and **free** methods on other operating systems to allocate and retrieve memory. Memory allocation performed by unmanaged code must also use these methods. + +## Passing Arrays to COM + + All managed array types can be passed to unmanaged code from managed code. Depending on the managed type and the attributes applied to it, the array can be accessed as a safe array or a C-style array, as shown in the following table. + +|Managed array type|Exported as| +|------------------------|-----------------| +|**ELEMENT_TYPE_SZARRAY** **\<** *type* **>**| **.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type is provided in the signature. Rank is always 1, lower bound is always 0. Size is always known at run time.| +|**ELEMENT_TYPE_ARRAY** **\<** *type* **>** **\<** *rank* **>**[**\<** *bounds* **>**]|**UnmanagedType.SafeArray(** *type* **)**

**UnmanagedType.LPArray**

Type, rank, bounds are provided in the signature. Size is always known at run time.| +|**ELEMENT_TYPE_CLASS** **\<****>**|**UT_Interface**

**UnmanagedType.SafeArray(** *type* **)**

Type, rank, bounds, and size are always known at run time.| + + There is a limitation in OLE Automation relating to arrays of structures that contain LPSTR or LPWSTR. Therefore, **String** fields have to be marshalled as **UnmanagedType.BSTR**. Otherwise, an exception will be thrown. + +### ELEMENT_TYPE_SZARRAY + + When a method containing an **ELEMENT_TYPE_SZARRAY** parameter (one-dimensional array) is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The same conversion rules apply to the array element types. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: + +#### Managed signature + +```vb +Sub [New](ar() As Long) +Sub [New](ar() As String) +``` + +```csharp +void New(long[] ar ); +void New(String[] ar ); +``` + +#### Unmanaged signature + ```cpp HRESULT New([in] SAFEARRAY( long ) ar); -HRESULT New([in] SAFEARRAY( BSTR ) ar); -``` - - The rank of the safe arrays is always 1 and the lower bound is always 0. The size is determined at run time by the size of the managed array being passed. - - The array can also be marshalled as a C-style array by using the attribute. For example: - -#### Managed signature - -```vb -Sub [New]( _ - ar() As Long, size as Integer) -Sub [New]( _ - ar() As String, size as Integer) -Sub [New]( _ - ar() As String, size as Integer) -``` - -```csharp +HRESULT New([in] SAFEARRAY( BSTR ) ar); +``` + + The rank of the safe arrays is always 1 and the lower bound is always 0. The size is determined at run time by the size of the managed array being passed. + + The array can also be marshalled as a C-style array by using the attribute. For example: + +#### Managed signature + +```vb +Sub [New]( _ + ar() As Long, size as Integer) +Sub [New]( _ + ar() As String, size as Integer) +Sub [New]( _ + ar() As String, size as Integer) +``` + +```csharp void New([MarshalAs(UnmanagedType.LPArray, SizeParamIndex=1)] - long [] ar, int size ); + long [] ar, int size ); void New([MarshalAs(UnmanagedType.LPArray, SizeParamIndex=1)] - String [] ar, int size ); + String [] ar, int size ); void New([MarshalAs(UnmanagedType.LPArray, ArraySubType= UnmanagedType.LPStr, SizeParamIndex=1)] - String [] ar, int size ); -``` - -#### Unmanaged signature - + String [] ar, int size ); +``` + +#### Unmanaged signature + ```cpp HRESULT New(long ar[]); HRESULT New(BSTR ar[]); -HRESULT New(LPStr ar[]); -``` - - Although the marshaller has the length information needed to marshal the array, the array length is usually passed as a separate argument to convey the length to the callee. - -### ELEMENT_TYPE_ARRAY - - When a method containing an **ELEMENT_TYPE_ARRAY** parameter is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: - -#### Managed signature - -```vb -Sub [New](ar(,) As Long) -Sub [New](ar(,) As String) -``` - -```csharp -void New( long [,] ar ); -void New( String [,] ar ); -``` - -#### Unmanaged signature - +HRESULT New(LPStr ar[]); +``` + + Although the marshaller has the length information needed to marshal the array, the array length is usually passed as a separate argument to convey the length to the callee. + +### ELEMENT_TYPE_ARRAY + + When a method containing an **ELEMENT_TYPE_ARRAY** parameter is exported from a .NET assembly to a type library, the array parameter is converted to a **SAFEARRAY** of a given type. The contents of the managed array are automatically copied from managed memory into the **SAFEARRAY**. For example: + +#### Managed signature + +```vb +Sub [New](ar(,) As Long) +Sub [New](ar(,) As String) +``` + +```csharp +void New( long [,] ar ); +void New( String [,] ar ); +``` + +#### Unmanaged signature + ```cpp HRESULT New([in] SAFEARRAY( long ) ar); -HRESULT New([in] SAFEARRAY( BSTR ) ar); -``` - - The rank, size, and bounds of the safe arrays are determined at run time by the characteristics of the managed array. - - The array can also be marshalled as a C-style array by applying the attribute. For example: - -#### Managed signature - -```vb -Sub [New]( _ - ar(,) As Long, size As Integer) -Sub [New]( _ - ar(,) As String, size As Integer) -``` - -```csharp +HRESULT New([in] SAFEARRAY( BSTR ) ar); +``` + + The rank, size, and bounds of the safe arrays are determined at run time by the characteristics of the managed array. + + The array can also be marshalled as a C-style array by applying the attribute. For example: + +#### Managed signature + +```vb +Sub [New]( _ + ar(,) As Long, size As Integer) +Sub [New]( _ + ar(,) As String, size As Integer) +``` + +```csharp void New([MarshalAs(UnmanagedType.LPARRAY, SizeParamIndex=1)] - long [,] ar, int size ); + long [,] ar, int size ); void New([MarshalAs(UnmanagedType.LPARRAY, ArraySubType= UnmanagedType.LPStr, SizeParamIndex=1)] - String [,] ar, int size ); -``` - -#### Unmanaged signature - + String [,] ar, int size ); +``` + +#### Unmanaged signature + ```cpp HRESULT New(long ar[]); -HRESULT New(LPStr ar[]); -``` - - Nested arrays cannot be marshalled. For example, the following signature generates an error when exported with the [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md). - -#### Managed signature - -```vb -Sub [New](ar()()() As Long) -``` - -```csharp -void New(long [][][] ar ); -``` - -### ELEMENT_TYPE_CLASS \ - - When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshalled as a **SAFEARRAY** by using the attribute. When marshalled as a safe array, the array elements are marshalled as variants. For example: - -#### Managed signature - -```vb -Sub New1( ar As System.Array ) -Sub New2( ar As System.Array ) -``` - -```csharp -void New1( System.Array ar ); -void New2( [MarshalAs(UnmanagedType.Safe array)] System.Array ar ); -``` - -#### Unmanaged signature - +HRESULT New(LPStr ar[]); +``` + + Nested arrays cannot be marshalled. For example, the following signature generates an error when exported with the [Type Library Exporter (Tlbexp.exe)](../tools/tlbexp-exe-type-library-exporter.md). + +#### Managed signature + +```vb +Sub [New](ar()()() As Long) +``` + +```csharp +void New(long [][][] ar ); +``` + +### ELEMENT_TYPE_CLASS \ + + When a method containing a parameter is exported from a .NET assembly to a type library, the array parameter is converted to an **_Array** interface. The contents of the managed array are accessible only through the methods and properties of the **_Array** interface. **System.Array** can also be marshalled as a **SAFEARRAY** by using the attribute. When marshalled as a safe array, the array elements are marshalled as variants. For example: + +#### Managed signature + +```vb +Sub New1( ar As System.Array ) +Sub New2( ar As System.Array ) +``` + +```csharp +void New1( System.Array ar ); +void New2( [MarshalAs(UnmanagedType.Safe array)] System.Array ar ); +``` + +#### Unmanaged signature + ```cpp HRESULT New([in] _Array *ar); -HRESULT New([in] SAFEARRAY(VARIANT) ar); -``` - -### Arrays within Structures - - Unmanaged structures can contain embedded arrays. By default, these embedded array fields are marshalled as a SAFEARRAY. In the following example, `s1` is an embedded array that is allocated directly within the structure itself. - -#### Unmanaged representation - +HRESULT New([in] SAFEARRAY(VARIANT) ar); +``` + +### Arrays within Structures + + Unmanaged structures can contain embedded arrays. By default, these embedded array fields are marshalled as a SAFEARRAY. In the following example, `s1` is an embedded array that is allocated directly within the structure itself. + +#### Unmanaged representation + ```cpp -struct MyStruct { - short s1[128]; -} -``` - - Arrays can be marshalled as , which requires you to set the field. The size can be set only as a constant. The following code shows the corresponding managed definition of `MyStruct`. - -```vb -Public Structure MyStruct - Public _ - s1() As Short -End Structure -``` - -```csharp -[StructLayout(LayoutKind.Sequential)] -public struct MyStruct { - [MarshalAs(UnmanagedType.ByValArray, SizeConst=128)] public short[] s1; -} -``` - +struct MyStruct { + short s1[128]; +} +``` + + Arrays can be marshalled as , which requires you to set the field. The size can be set only as a constant. The following code shows the corresponding managed definition of `MyStruct`. + +```vb +Public Structure MyStruct + Public _ + s1() As Short +End Structure +``` + +```csharp +[StructLayout(LayoutKind.Sequential)] +public struct MyStruct { + [MarshalAs(UnmanagedType.ByValArray, SizeConst=128)] public short[] s1; +} +``` + ## See also - [Default Marshalling Behavior](default-marshalling-behavior.md) diff --git a/docs/framework/migration-guide/versions-and-dependencies.md b/docs/framework/migration-guide/versions-and-dependencies.md index 021bc5dc87c4b..fd8008d645d49 100644 --- a/docs/framework/migration-guide/versions-and-dependencies.md +++ b/docs/framework/migration-guide/versions-and-dependencies.md @@ -53,7 +53,7 @@ Jump to: - [New features](../whats-new/index.md#whats-new-in-net-framework-481) - New accessibility features -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net481/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net481/README.md) | | Versions | |-|-| @@ -72,7 +72,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins - [New features](../whats-new/index.md#whats-new-in-net-framework-48) - [New in accessibility](../whats-new/whats-new-in-accessibility.md#whats-new-in-accessibility-in-net-framework-48) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net48/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net48/README.md) | | Versions | |-|-| @@ -93,7 +93,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins - [New features](../whats-new/index.md#whats-new-in-net-framework-472) - [New in accessibility](../whats-new/whats-new-in-accessibility.md#whats-new-in-accessibility-in-net-framework-472) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net472/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net472/README.md) | | Versions | |-|-| @@ -116,7 +116,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins - [New features](../whats-new/index.md#whats-new-in-net-framework-471) - [New in accessibility](../whats-new/whats-new-in-accessibility.md#whats-new-in-accessibility-in-net-framework-471) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net471/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net471/README.md) | | Versions | |-|-| @@ -134,7 +134,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins ### .NET Framework 4.7 - [New features](../whats-new/index.md#whats-new-in-net-framework-47) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net47/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net47/README.md) | | Versions | |--------------------|-------------------------------------------------------------------------------------------------------| @@ -152,7 +152,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins ### .NET Framework 4.6.2 - [New features](../whats-new/index.md#whats-new-in-net-framework-462) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net462/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net462/README.md) | | Versions | |--------------------|------------------------------------------------------------------------------------------------------------| @@ -170,7 +170,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins ### .NET Framework 4.6.1 - [New features](../whats-new/index.md#whats-new-in-net-framework-461) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net461/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net461/README.md) | | Versions | |---------------------------------------|---------------------------------------------------------------------------| @@ -191,7 +191,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins ### .NET Framework 4.6 - [New features](../whats-new/index.md#whats-new-in-net-2015) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net46/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net46/README.md) | | Versions | |---------------------------------------|----------------------------------------------------------| @@ -210,7 +210,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins ### .NET Framework 4.5.2 - [New features](../whats-new/index.md#whats-new-in-net-framework-452) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net452/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net452/README.md) | | Versions | |--------------------|----------------------------------------------------------| @@ -223,7 +223,7 @@ To determine the installed .NET version, use `Release` DWORD 379893. For more in ### .NET Framework 4.5.1 - [New features](../whats-new/index.md#whats-new-in-net-framework-451) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net451/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net451/README.md) | | Versions | |---------------------------------------|----------------------------------------------------------------| @@ -244,7 +244,7 @@ For more information, see [instructions](how-to-determine-which-versions-are-ins ### .NET Framework 4.5 - [New features](../whats-new/index.md#whats-new-in-net-framework-45) -- [Release notes](https://github.com/Microsoft/dotnet/tree/master/releases/net45/README.md) +- [Release notes](https://github.com/Microsoft/dotnet/tree/main/releases/net45/README.md) | | Versions | |---------------------------------------|-------------------------------------------| diff --git a/docs/framework/network-programming/tls.md b/docs/framework/network-programming/tls.md index ca0a6cfb2c766..eb101b7678ee0 100644 --- a/docs/framework/network-programming/tls.md +++ b/docs/framework/network-programming/tls.md @@ -1,8 +1,9 @@ --- -title: Transport Layer Security (TLS) best practices with the .NET Framework -description: Describes best practices using Transport Layer Security (TLS) with the .NET Framework +title: Transport Layer Security (TLS) best practices with .NET Framework +titleSuffix: "" +description: Describes best practices using Transport Layer Security (TLS) with .NET Framework ms.date: 03/18/2024 -helpviewer_keywords: +helpviewer_keywords: - "sending data, Internet security" - "protocols, Internet security" - "Network security" @@ -13,10 +14,10 @@ helpviewer_keywords: - "security [.NET Framework], Internet" - "permissions [.NET Framework], Internet" --- -# Transport Layer Security (TLS) best practices with the .NET Framework +# Transport Layer Security (TLS) best practices with .NET Framework > [!NOTE] -> This page contains .NET Framework TLS information. If you're looking for .NET TLS information, see: [TLS/SSL Best Practices](https://learn.microsoft.com/dotnet/core/extensions/sslstream-best-practices) +> This page contains .NET Framework TLS information. If you're looking for .NET TLS information, see: [TLS/SSL Best Practices](../../core/extensions/sslstream-best-practices.md) .NET Framework supports the use of the Transport Layer Security (TLS) protocol to secure network communications. @@ -48,7 +49,7 @@ Here is an updated example table showing the highest supported TLS version for d | 4.8 | TLS 1.2 | **TLS 1.3**| | 4.8.1 | TLS 1.2 | **TLS 1.3**| -For more information see [TLS protocol version support in Schannel](https://learn.microsoft.com/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-#tls-protocol-version-support). +For more information see [TLS protocol version support in Schannel](/windows/win32/secauthn/protocols-in-tls-ssl--schannel-ssp-#tls-protocol-version-support). ## Recommendations @@ -207,7 +208,7 @@ A value of `false` for `Switch.System.Net.DontEnableSystemDefaultTlsVersions` ca If your app targets .NET Framework 4.7 or later versions, this switch defaults to `false`. That's a secure default that we recommend. If your app runs on .NET Framework 4.7 or later versions, but targets an earlier version, the switch defaults to `true`. In that case, you should explicitly set it to `false`. -### For WCF Applications +### For WCF applications #### Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols @@ -284,7 +285,7 @@ You can use the registry for fine-grained control over the protocols that your c Start with the `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols` registry key. Under that key you can create any subkeys in the set `TLS 1.2`, `TLS 1.3`. Under each of those subkeys, you can create subkeys `Client` and/or `Server`. Under `Client` and `Server`, you can create DWORD values `DisabledByDefault` (0 or 1) and `Enabled` (0 or 1). -For more information see: [TLS Registry Settings - Schannel](https://learn.microsoft.com/windows-server/security/tls/tls-registry-settings?tabs=diffie-hellman#tls-dtls-and-ssl-protocol-version-settings) +For more information see: [TLS Registry Settings - Schannel](/windows-server/security/tls/tls-registry-settings?tabs=diffie-hellman#tls-dtls-and-ssl-protocol-version-settings) ## The SCH_USE_STRONG_CRYPTO flag diff --git a/docs/framework/performance/clr-etw-events.md b/docs/framework/performance/clr-etw-events.md index 6f23c14b3b2fd..5e0510340a804 100644 --- a/docs/framework/performance/clr-etw-events.md +++ b/docs/framework/performance/clr-etw-events.md @@ -2,7 +2,7 @@ title: "CLR ETW Events" description: "See articles about common language runtime (CLR) event tracing for Windows (ETW) events. There are two event providers: runtime provider and rundown provider." ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "CLR ETW events" - "ETW, common language runtime" - "ETW, CLR events" @@ -10,52 +10,52 @@ ms.assetid: ef2b31c3-7426-43e7-9924-92339b96556d --- # CLR ETW Events -The topics in this section describe event tracing for Windows (ETW) events. Each event has an associated keyword and level, which are described in the [CLR ETW Keywords and Levels](clr-etw-keywords-and-levels.md) topic. The CLR has two providers for the events: - -- The runtime provider, which raises events depending on which keywords (categories of events) are enabled. The CLR runtime provider GUID is e13c0d23-ccbc-4e12-931b-d9cc2eee27e4. - -- The rundown provider, which has special-purpose uses. The CLR rundown provider GUID is a669021c-c450-4609-a035-5af59af4df18. - - For more information about the providers, see [CLR ETW Providers](clr-etw-providers.md). - -## In This Section - - [Runtime Information Events](runtime-information-etw-events.md) - Captures information about the runtime, including the SKU, version number, the manner in which the runtime was activated, the command-line parameters it was started with, the GUID (if applicable), and other relevant information. - - [Exception Thrown_V1 Event](exception-thrown-v1-etw-event.md) - Captures information about exceptions that are thrown. - - [Contention Events](contention-etw-events.md) - Captures information about contention for monitor locks or native locks that the runtime uses. - - [Thread Pool Events](thread-pool-etw-events.md) - Captures information about worker thread pools and I/O thread pools. - - [Loader Events](loader-etw-events.md) - Captures information about loading and unloading application domains, assemblies, and modules. - - [Method Events](method-etw-events.md) - Captures information about CLR methods for symbol resolution. - - [Garbage Collection Events](garbage-collection-etw-events.md) - Captures information pertaining to garbage collection, to help in diagnostics and debugging. - - [JIT Tracing Events](jit-tracing-etw-events.md) - Captures information about just-in-time (JIT) inlining and tail calls. - - [Interop Events](interop-etw-events.md) - Captures information about Microsoft intermediate language (MSIL) stub generation and caching. - - [ARM Events](application-domain-resource-monitoring-arm-etw-events.md) - Captures detailed diagnostic information about the state of an application domain. - - [Security Events](security-etw-events.md) - Captures information about strong name and Authenticode verification. - - [Stack Event](stack-etw-event.md) - Captures information that is used with other events to generate stack traces after an event is raised. - +The topics in this section describe event tracing for Windows (ETW) events. Each event has an associated keyword and level, which are described in the [CLR ETW Keywords and Levels](clr-etw-keywords-and-levels.md) topic. The CLR has two providers for the events: + +- The runtime provider, which raises events depending on which keywords (categories of events) are enabled. The CLR runtime provider GUID is e13c0d23-ccbc-4e12-931b-d9cc2eee27e4. + +- The rundown provider, which has special-purpose uses. The CLR rundown provider GUID is a669021c-c450-4609-a035-5af59af4df18. + + For more information about the providers, see [CLR ETW Providers](clr-etw-providers.md). + +## In This Section + + [Runtime Information Events](runtime-information-etw-events.md) + Captures information about the runtime, including the SKU, version number, the manner in which the runtime was activated, the command-line parameters it was started with, the GUID (if applicable), and other relevant information. + + [Exception Thrown_V1 Event](exception-thrown-v1-etw-event.md) + Captures information about exceptions that are thrown. + + [Contention Events](contention-etw-events.md) + Captures information about contention for monitor locks or native locks that the runtime uses. + + [Thread Pool Events](thread-pool-etw-events.md) + Captures information about worker thread pools and I/O thread pools. + + [Loader Events](loader-etw-events.md) + Captures information about loading and unloading application domains, assemblies, and modules. + + [Method Events](method-etw-events.md) + Captures information about CLR methods for symbol resolution. + + [Garbage Collection Events](garbage-collection-etw-events.md) + Captures information pertaining to garbage collection, to help in diagnostics and debugging. + + [JIT Tracing Events](jit-tracing-etw-events.md) + Captures information about just-in-time (JIT) inlining and tail calls. + + [Interop Events](interop-etw-events.md) + Captures information about common intermediate language (CIL) stub generation and caching. + + [ARM Events](application-domain-resource-monitoring-arm-etw-events.md) + Captures detailed diagnostic information about the state of an application domain. + + [Security Events](security-etw-events.md) + Captures information about strong name and Authenticode verification. + + [Stack Event](stack-etw-event.md) + Captures information that is used with other events to generate stack traces after an event is raised. + ## See also - [Improve Debugging And Performance Tuning With ETW](/archive/msdn-magazine/2007/april/event-tracing-improve-debugging-and-performance-tuning-with-etw) diff --git a/docs/framework/performance/interop-etw-events.md b/docs/framework/performance/interop-etw-events.md index a30aef0363f06..28b727c7136ea 100644 --- a/docs/framework/performance/interop-etw-events.md +++ b/docs/framework/performance/interop-etw-events.md @@ -1,6 +1,6 @@ --- title: "Interop ETW Events" -description: Review interop ETW (event tracing for Windows) events, which capture information about Microsoft intermediate language (MSIL) stub generation & caching in .NET. +description: Review interop ETW (event tracing for Windows) events, which capture information about common intermediate language (CIL) stub generation & caching in .NET. ms.date: "03/30/2017" helpviewer_keywords: - "interop events [.NET Framework]" @@ -8,7 +8,7 @@ helpviewer_keywords: --- # Interop ETW Events -Interop events capture information about Microsoft intermediate language (MSIL) stub generation and caching. +Interop events capture information about common intermediate language (CIL) stub generation and caching. ## ILStubGenerated Event @@ -22,7 +22,7 @@ The following table shows the keyword and level. (For more information, see [CLR |Event|Event ID|Raised when| |-----------|--------------|-----------------| -|`ILStubGenerated`|88|The MSIL stub has been generated.| +|`ILStubGenerated`|88|The CIL stub has been generated.| The following table shows the event data. @@ -37,7 +37,7 @@ The following table shows the keyword and level. (For more information, see [CLR |ManagedInteropMethodSignature|win:UnicodeString|The signature of the managed interop method.| |NativeMethodSignature|win:UnicodeString|The native method signature.| |StubMethodSignature|win:UnicodeString|The stub method signature.| -|StubMethodILCode|win:UnicodeString|The MSIL code for the stub method.| +|StubMethodILCode|win:UnicodeString|The CIL code for the stub method.| |ClrInstanceID|win:UInt16|Unique ID for the instance of CLR or CoreCLR.| ## ILStubCacheHit Event @@ -52,7 +52,7 @@ The following table shows the keyword and level. |Event|Event ID|Raised when| |-----------|--------------|-----------------| -|`ILStubCacheHit`|89|The MSIL cache has been accessed.| +|`ILStubCacheHit`|89|The CIL cache has been accessed.| The following table shows the event data. diff --git a/docs/framework/performance/loader-etw-events.md b/docs/framework/performance/loader-etw-events.md index 171bd9b3073f9..ba77e6af81b8b 100644 --- a/docs/framework/performance/loader-etw-events.md +++ b/docs/framework/performance/loader-etw-events.md @@ -98,7 +98,7 @@ These events collect information relating to loading and unloading application d |AssemblyID|win:UInt64|ID of the assembly in which this module resides.| |ModuleFlags|win:UInt32|0x1: Domain neutral module.

0x2: Module has a native image.

0x4: Dynamic module.

0x8: Manifest module.| |Reserved1|win:UInt32|Reserved field.| -|ModuleILPath|win:UnicodeString|Path of the Microsoft intermediate language (MSIL) image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| +|ModuleILPath|win:UnicodeString|Path of the common intermediate language (CIL) image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| |ModuleNativePath|win:UnicodeString|Path of the module native image, if present (null-terminated).| |ClrInstanceID|win:UInt16|Unique ID for the instance of CLR or CoreCLR.| |ManagedPdbSignature|win:GUID|GUID signature of the managed program database (PDB) that matches this module. (See Remarks.)| @@ -112,7 +112,7 @@ These events collect information relating to loading and unloading application d - The fields that have "Pdb" in their names can be used by profiling tools to locate PDBs that match the modules that were loaded during the profiling session. The values of these fields correspond to the data written into the IMAGE_DIRECTORY_ENTRY_DEBUG sections of the module normally used by debuggers to help locate PDBs that match the loaded modules. -- The field names that begin with "ManagedPdb" refer to the managed PDB corresponding to the MSIL module that was generated by the managed compiler (such as the C# or Visual Basic compiler). This PDB uses the managed PDB format, and describes how elements from the original managed source code, such as files, line numbers, and symbol names, map to MSIL elements that are compiled into the MSIL module. +- The field names that begin with "ManagedPdb" refer to the managed PDB corresponding to the CIL module that was generated by the managed compiler (such as the C# or Visual Basic compiler). This PDB uses the managed PDB format, and describes how elements from the original managed source code, such as files, line numbers, and symbol names, map to CIL elements that are compiled into the CIL module. - The field names that begin with "NativePdb" refer to the NGen PDB generated by calling `NGEN createPDB`. This PDB uses the native PDB format, and describes how elements from the original managed source code, such as files, line numbers, and symbol names, map to native elements that are compiled into the NGen module. @@ -143,7 +143,7 @@ These events collect information relating to loading and unloading application d |AppDomainID|win:UInt64|ID of the application domain in which this module is used.| |ModuleFlags|win:UInt32|0x1: Domain neutral module.

0x2: Module has a native image.

0x4: Dynamic module.

0x8: Manifest module.| |Reserved1|win:UInt32|Reserved field.| -|ModuleILPath|win:UnicodeString|Path of the MSIL image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| +|ModuleILPath|win:UnicodeString|Path of the CIL image for the module, or dynamic module name if it is a dynamic assembly (null-terminated).| |ModuleNativePath|win:UnicodeString|Path of the module native image, if present (null-terminated).| |ClrInstanceID|win:UInt16|Unique ID for the instance of CLR or CoreCLR.| diff --git a/docs/framework/performance/method-etw-events.md b/docs/framework/performance/method-etw-events.md index 1204bf711c223..81a8300d4dd4f 100644 --- a/docs/framework/performance/method-etw-events.md +++ b/docs/framework/performance/method-etw-events.md @@ -133,7 +133,7 @@ The following table shows the event data: |MethodID|win:UInt64|Unique identifier of the method.| |ModuleID|win:UInt64|Identifier of the module to which this method belongs.| |MethodToken|win:UInt32|0 for dynamic methods and JIT helpers.| -|MethodILSize|win:UInt32|The size of the Microsoft intermediate language (MSIL) for the method that is being JIT-compiled.| +|MethodILSize|win:UInt32|The size of the common intermediate language (CIL) for the method that is being JIT-compiled.| |MethodNameSpace|win:UnicodeString|Full class name associated with the method.| |MethodName|win:UnicodeString|Name of the method.| |MethodSignature|win:UnicodeString|Signature of the method (comma-separated list of type names).| diff --git a/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md b/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md index 9e7b4a13e724d..71e9563509755 100644 --- a/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md +++ b/docs/framework/reflection-and-codedom/security-issues-in-reflection-emit.md @@ -15,7 +15,7 @@ ms.assetid: 0f8bf8fa-b993-478f-87ab-1a1a7976d298 --- # Security Issues in Reflection Emit -.NET Framework provides three ways to emit Microsoft intermediate language (MSIL), each with its own security issues: +.NET Framework provides three ways to emit common intermediate language (CIL), each with its own security issues: - [Dynamic Assemblies](#dynamic-assemblies) - [Anonymously Hosted Dynamic Methods](#anonymously-hosted-dynamic-methods) @@ -59,7 +59,7 @@ ms.assetid: 0f8bf8fa-b993-478f-87ab-1a1a7976d298 Instead, when an anonymously hosted dynamic method is created, the call stack is captured. When the method is constructed, security demands are made against the captured call stack. > [!NOTE] -> Conceptually, demands are made during the construction of the method. That is, demands could be made as each MSIL instruction is emitted. In the current implementation, all demands are made when the method is called or when the just-in-time (JIT) compiler is invoked, if the method is invoked without calling . +> Conceptually, demands are made during the construction of the method. That is, demands could be made as each CIL instruction is emitted. In the current implementation, all demands are made when the method is called or when the just-in-time (JIT) compiler is invoked, if the method is invoked without calling . If the application domain permits it, anonymously hosted dynamic methods can skip JIT visibility checks, subject to the following restriction: The nonpublic types and members accessed by an anonymously hosted dynamic method must be in assemblies whose grant sets are equal to, or subsets of, the grant set of the emitting call stack. This restricted ability to skip JIT visibility checks is enabled if the application domain grants with the flag. diff --git a/docs/framework/release-notes/2024/04-april-security-and-quality-rollup.md b/docs/framework/release-notes/2024/04-april-security-and-quality-rollup.md new file mode 100644 index 0000000000000..d149b87947df1 --- /dev/null +++ b/docs/framework/release-notes/2024/04-april-security-and-quality-rollup.md @@ -0,0 +1,114 @@ +--- +title: April 2024 security and quality rollup +description: Learn about the improvements in the .NET Framework April 2024 security and quality rollup. +ms.date: 04/17/2024 +--- +# April 2024 security and quality rollup + +_Released April 9, 2024_ + +## Summary of what's new in this release + +- [Security improvements](#security-improvements) +- [Quality and reliability improvements](#quality-and-reliability-improvements) + +### Security improvements + +#### CVE-2024-21409 – Remote code execution vulnerability + +This security update addresses a remote code execution vulnerability detailed in [CVE 2024-21409](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2024-21409). + +#### Defense in depth vulnerability + +This security update addresses an issue where version of the OSS zlib library is out of date. + +#### Defense in depth vulnerability + +This security update addresses an issue in AIA fetching process. + +### Quality and reliability improvements + +This release contains the following quality and reliability improvements. + +#### ASP.NET + +Addresses an issue with `JavaScriptSerializer` where after installing the January Security and Quality update, there is a performance degradation. (*Applies to: .NET Framework 4.6.2, 4.7, 4.7.1,4.7.2, 4.8, 4.8.1.*) + +#### CLR + +Addressed an issue with thread pool recycled lists becoming unresponsive on multi-CPU-group computers. (*Applies to: .NET Framework 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1.*) + +Addressed an issue where Interlocked.Read from 32-bit apps are much slower on some computers. (*Applies to: .NET Framework 4.8.1.*) + +#### Compilers + +Addresses an issue when the native C# compiler (csc.exe) is used to compile code making calls to COM interop assemblies. (*Applies to: .NET Framework 4.8.1.*) + +## Known issues + +This release contains no known issues. + +## Summary tables + +The following table outlines the updates in this release. + +| Product version | Cumulative update | +| --- | --- | +| **Microsoft server operating system, version 23H2** | | +| .NET Framework 3.5, 4.8.1 | [5036617](https://support.microsoft.com/kb/5036617) | +| **Windows 11, version 22H2 and Windows 11, version 23H2** | | +| .NET Framework 3.5, 4.8.1 | [5036620](https://support.microsoft.com/kb/5036620) | +| **Windows 11, version 21H2** | **[5037037](https://support.microsoft.com/kb/5037037)** | +| .NET Framework 3.5, 4.8 | [5036611](https://support.microsoft.com/kb/5036611) | +| .NET Framework 3.5, 4.8.1 | [5036619](https://support.microsoft.com/kb/5036619) | +| **Microsoft server operating system, version 22H2 and version 21H2** | **[5037033](https://support.microsoft.com/kb/5037033)** | +| .NET Framework 3.5, 4.8 | [5036613](https://support.microsoft.com/kb/5036613) | +| .NET Framework 3.5, 4.8.1 | [5036621](https://support.microsoft.com/kb/5036621) | +| **Windows 10, version 22H2** | **[5037036](https://support.microsoft.com/kb/5037036)** | +| .NET Framework 3.5, 4.8 | [5036608](https://support.microsoft.com/kb/5036608) | +| .NET Framework 3.5, 4.8.1 | [5036618](https://support.microsoft.com/kb/5036618) | +| **Windows 10, version 21H2** | **[5037035](https://support.microsoft.com/kb/5037035)** | +| .NET Framework 3.5, 4.8 | [5036608](https://support.microsoft.com/kb/5036608) | +| .NET Framework 3.5, 4.8.1 | [5036618](https://support.microsoft.com/kb/5036618) | +| **Windows 10 1809 and Windows Server 2019** | **[5037034](https://support.microsoft.com/kb/5037034)** | +| .NET Framework 3.5, 4.7.2 | [5036604](https://support.microsoft.com/kb/5036604) | +| .NET Framework 3.5, 4.8 | [5036610](https://support.microsoft.com/kb/5036610) | +| **Windows 10 1607 and Windows Server 2016** | | +| .NET Framework 3.5, 4.6.2, 4.7, 4.7.1, 4.7.2 | [5032197](https://support.microsoft.com/kb/5032197) | +| .NET Framework 4.8 | [5036609](https://support.microsoft.com/kb/5036609) | +| **Windows 10 1507** | | +| .NET Framework 3.5, 4.6, 4.6.2 | [5032199](https://support.microsoft.com/kb/5032199) | + +The following table is for earlier Windows and Windows Server versions for Security and Quality Rollup updates.   + +| Product version | Security and quality rollup | +| --- | --- | +| **Windows Server 2012 R2** | **[5037040](https://support.microsoft.com/kb/5037040)** | +| .NET Framework 3.5 | [5036627](https://support.microsoft.com/kb/5036627) | +| .NET Framework 4.6.2, 4.7, 4.7.1, 4.7.2 | [5036606](https://support.microsoft.com/kb/5036606) | +| .NET Framework 4.8 | [5036614](https://support.microsoft.com/kb/5036614) | +| **Windows Server 2012** | **[5037039](https://support.microsoft.com/kb/5037039)** | +| .NET Framework 3.5 | [5036624](https://support.microsoft.com/kb/5036624) | +| .NET Framework 4.6.2, 4.7, 4.7.1, 4.7.2 | [5036605](https://support.microsoft.com/kb/5036605) | +| .NET Framework 4.8 | [5036612](https://support.microsoft.com/kb/5036612) | +| **Windows Server 2008 R2** | **[5037038](https://support.microsoft.com/kb/5037038)** | +| .NET Framework 3.5.1 | [5036626](https://support.microsoft.com/kb/5036626) | +| .NET Framework 4.6.2, 4.7, 4.7.1, 4.7.2 | [5036607](https://support.microsoft.com/kb/5036607) | +| .NET Framework 4.8 |[5036615](https://support.microsoft.com/kb/5036615) | +| **Windows Server 2008** | **[5037041](https://support.microsoft.com/kb/5037041)** | +| .NET Framework 2.0, 3.0 | [5036625](https://support.microsoft.com/kb/5036625) | +| .NET Framework 3.5 SP1 | [5036637](https://support.microsoft.com/kb/5036637) | +| .NET Framework 4.6.2 | [5036607](https://support.microsoft.com/kb/5036607) | + +The following table is for earlier Windows and Windows Server versions for Security Only updates, which aren't cumulative. + +| Product version | Security only update | +| --- | --- | +| **Windows Server 2008 R2** | **[5037127](https://support.microsoft.com/kb/5037127)** | +| .NET Framework 3.5.1 | [5036634](https://support.microsoft.com/kb/5036634) | +| .NET Framework 4.6.2, 4.7, 4.7.1, 4.7.2 | [5036631](https://support.microsoft.com/kb/5036631) | +| .NET Framework 4.8 |[5036632](https://support.microsoft.com/kb/5036632) | +| **Windows Server 2008** | **[5037128](https://support.microsoft.com/kb/5037128)** | +| .NET Framework 2.0, 3.0 | [5036633](https://support.microsoft.com/kb/5036633) | +| .NET Framework 3.5 SP1 | [5036636](https://support.microsoft.com/kb/5036636) | +| .NET Framework 4.6.2 | [5036631](https://support.microsoft.com/kb/5036631) | diff --git a/docs/framework/toc.yml b/docs/framework/toc.yml index 01c572331bfad..a5c80561bc78c 100644 --- a/docs/framework/toc.yml +++ b/docs/framework/toc.yml @@ -667,6 +667,10 @@ items: href: /dotnet/api/?view=point-of-service-1.14&preserve-view=true - name: What's new and obsolete items: + - name: Release notes + items: + - name: April 2024 security and quality rollup + href: release-notes/2024/04-april-security-and-quality-rollup.md - name: What's new href: whats-new/index.md - name: What's new in accessibility diff --git a/docs/framework/tools/al-exe-assembly-linker.md b/docs/framework/tools/al-exe-assembly-linker.md index 70f1f6095ac8b..e22289e17d474 100644 --- a/docs/framework/tools/al-exe-assembly-linker.md +++ b/docs/framework/tools/al-exe-assembly-linker.md @@ -43,30 +43,30 @@ You can specify the following `options`; you must specify **/out**. |**/algid:** `id`|Specifies an algorithm to hash all files in a multifile assembly except the file that contains the assembly manifest. The default algorithm is CALG_SHA1. See ALG_ID in the Platform SDK documentation for other algorithms. For the first release of the .NET Framework, only CALG_SHA1 and CALG_MD5 are valid.

The hash values are stored in the file table of the assembly manifest. At installation and load time, the assembly's files are checked against their hashes.

You can also specify this option as a custom attribute () in the source code for any module.| |**/base[address]:** `addr`|Specifies the address at which a DLL will be loaded on the user's computer at run time. Applications load faster if you specify the base address of the DLLs, instead of letting the operating system relocate the DLLs in the process space.| |**/bugreport**: `filename`|Creates a file (`filename`) that contains information for reporting bugs.| -|**/comp[any]:** `text`|Specifies a string for the Company field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, `text` appears in File Explorer as the `Company` property for the file. If you specify **/win32res**, the company information in the specified resource file appears as the `Company` property in File Explorer.

If text is an empty string (""), the Win32 `Company` resource appears as a single space.

If you specify **/win32res**, **/company** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/config[uration]:** `text`|Specifies a string for the Configuration field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If text is an empty string, the Win32 Configuration resource appears as a single space.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/copy[right]:** `text`|Specifies a string for the Copyright field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/copyright** appears in File Explorer as the Win32 Copyright resource.

If text is an empty string, the Win32 Copyright resource appears as a single space.

If you specify **/win32res**, **/copyright** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/c[ulture]:** `text`|Specifies the culture string to associate with the assembly. Valid values for cultures are those defined by the Internet Requests for Comments (RFC) document 1766 titled "Tags for the Identification of Languages."

Place the string in double quotation marks (" ") if `text` contains a space. There is no default culture string. This string is available for viewing with reflection.

For information about valid `text` strings, see the .

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|`/delay[sign][+ or -]`|Specifies whether the assembly will be fully or partially signed. Use **/delaysign-** if you want a fully signed assembly. Use **/delaysign+** if you only want to include the public key in the assembly.

When you request a fully signed assembly, *Al.exe* hashes the file that contains the manifest (assembly metadata) and signs that hash with the private key. The resulting digital signature is stored in the file that contains the manifest. When an assembly is delay signed, *Al.exe* does not compute and store the signature, but just reserves space in the file so the signature can be added later.

The default is **/delaysign-**.

The **/delaysign** option has no effect unless used with **/keyfile** or **/keyname**.

For example, using **/delaysign+** enables a tester to put the assembly in the global cache. After testing, you can fully sign the assembly by including the private key in the assembly.

Note: Before using the [*Gacutil.exe* (Global Assembly Cache Tool)](gacutil-exe-gac-tool.md) to put a delay-signed assembly into the global cache, use the [*Sn.exe* (Strong Name Tool)](sn-exe-strong-name-tool.md) to register the assembly for verification skipping. For example, `Sn.exe –Vr delaySignedAssembly`. Use this only for development.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/descr[iption]:** `text`|Specifies a string for the field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/description** appears in File Explorer as the Win32 **Comments** resource.

If text is an empty string, the Win32 **Comments** resource appears as a single space.

If you specify **/win32res**, **/description** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/comp[any]:** `text`|Specifies a string for the Company field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, `text` appears in File Explorer as the `Company` property for the file. If you specify **/win32res**, the company information in the specified resource file appears as the `Company` property in File Explorer.

If text is an empty string (""), the Win32 `Company` resource appears as a single space.

If you specify **/win32res**, **/company** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/config[uration]:** `text`|Specifies a string for the Configuration field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If text is an empty string, the Win32 Configuration resource appears as a single space.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/copy[right]:** `text`|Specifies a string for the Copyright field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/copyright** appears in File Explorer as the Win32 Copyright resource.

If text is an empty string, the Win32 Copyright resource appears as a single space.

If you specify **/win32res**, **/copyright** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/c[ulture]:** `text`|Specifies the culture string to associate with the assembly. Valid values for cultures are those defined by the Internet Requests for Comments (RFC) document 1766 titled "Tags for the Identification of Languages."

Place the string in double quotation marks (" ") if `text` contains a space. There is no default culture string. This string is available for viewing with reflection.

For information about valid `text` strings, see the .

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|`/delay[sign][+ or -]`|Specifies whether the assembly will be fully or partially signed. Use **/delaysign-** if you want a fully signed assembly. Use **/delaysign+** if you only want to include the public key in the assembly.

When you request a fully signed assembly, *Al.exe* hashes the file that contains the manifest (assembly metadata) and signs that hash with the private key. The resulting digital signature is stored in the file that contains the manifest. When an assembly is delay signed, *Al.exe* does not compute and store the signature, but just reserves space in the file so the signature can be added later.

The default is **/delaysign-**.

The **/delaysign** option has no effect unless used with **/keyfile** or **/keyname**.

For example, using **/delaysign+** enables a tester to put the assembly in the global cache. After testing, you can fully sign the assembly by including the private key in the assembly.

Note: Before using the [*Gacutil.exe* (Global Assembly Cache Tool)](gacutil-exe-gac-tool.md) to put a delay-signed assembly into the global cache, use the [*Sn.exe* (Strong Name Tool)](sn-exe-strong-name-tool.md) to register the assembly for verification skipping. For example, `Sn.exe –Vr delaySignedAssembly`. Use this only for development.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/descr[iption]:** `text`|Specifies a string for the field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/description** appears in File Explorer as the Win32 **Comments** resource.

If text is an empty string, the Win32 **Comments** resource appears as a single space.

If you specify **/win32res**, **/description** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/e[vidence]:** `file`|Embeds `file` in the assembly with the resource name of Security.Evidence.

You cannot use Security.Evidence for regular resources.| -|**/fileversion:** `version`|Specifies a string for the **File Version** field in the assembly. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/fileversion** will be used as the Win32 **File Version** resource. If you do not specify **/fileversion**, the Win32 **File Version** resource will be populated by the Win32 **Assembly Version** resource.

If **/win32res** is specified, **/fileversion** does not affect the Win32 resource.

You can also specify this option as a custom attribute (AssemblyFileVersionAttribute) in the source code for any MSIL module.| -|**/flags:** `flags`|Specifies a value for the `Flags` field in the assembly. Possible values for `flags`:

0x0000
The assembly is side-by-side compatible.

0x0010
The assembly cannot execute with other versions if they are executing in the same application domain.

0x0020
The assembly cannot execute with other versions if they are executing in the same process.

0x0030
The assembly cannot execute with other versions if they are executing on the same computer.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/fileversion:** `version`|Specifies a string for the **File Version** field in the assembly. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/fileversion** will be used as the Win32 **File Version** resource. If you do not specify **/fileversion**, the Win32 **File Version** resource will be populated by the Win32 **Assembly Version** resource.

If **/win32res** is specified, **/fileversion** does not affect the Win32 resource.

You can also specify this option as a custom attribute (AssemblyFileVersionAttribute) in the source code for any CIL module.| +|**/flags:** `flags`|Specifies a value for the `Flags` field in the assembly. Possible values for `flags`:

0x0000
The assembly is side-by-side compatible.

0x0010
The assembly cannot execute with other versions if they are executing in the same application domain.

0x0020
The assembly cannot execute with other versions if they are executing in the same process.

0x0030
The assembly cannot execute with other versions if they are executing on the same computer.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/fullpaths**|Causes *Al.exe* to use the absolute path for any files that are reported in an error message.| |**/help**|Displays command syntax and options for the tool.| -|**/keyf[ile]:** `filename`|Specifies a file (`filename`) that contains a key pair or just a public key to sign an assembly. The compiler inserts the public key in the assembly manifest and then signs the final assembly with the private key. See the [Strong Name Tool (*Sn.exe*)](sn-exe-strong-name-tool.md) for information about generating key files and installing key pairs into key containers.

If you are using delayed signing, this file will usually have the public key but not the private key.

The public key (of the key pair) information appears in the .publickey field of the assembly.

You can also specify this option as a custom attribute () in the source code for any MSIL module.

If both **/keyfile** and **/keyname** are specified (either by command-line option or by custom attribute) in the same compilation, *Al.exe* will first try the container specified with **/keyname**. If that succeeds, the assembly is signed with the information in the key container. If *Al.exe* does not find the key container, it will try the file specified with **/keyfile**. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to the -i option in [*Sn.exe*](sn-exe-strong-name-tool.md)) so that on the next compilation, the **/keyname** option will be valid.| -|**/keyn[ame]:** `text`|Specifies a container that holds a key pair. This will sign the assembly (give it a strong name) by inserting a public key into the assembly manifest. *Al.exe* will then sign the final assembly with the private key.

Use *Sn.exe* to generate a key pair.

The key information appears in the .publickey field of the assembly.

Place `text` in double quotation marks (" ") if there is an embedded space.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/keyf[ile]:** `filename`|Specifies a file (`filename`) that contains a key pair or just a public key to sign an assembly. The compiler inserts the public key in the assembly manifest and then signs the final assembly with the private key. See the [Strong Name Tool (*Sn.exe*)](sn-exe-strong-name-tool.md) for information about generating key files and installing key pairs into key containers.

If you are using delayed signing, this file will usually have the public key but not the private key.

The public key (of the key pair) information appears in the .publickey field of the assembly.

You can also specify this option as a custom attribute () in the source code for any CIL module.

If both **/keyfile** and **/keyname** are specified (either by command-line option or by custom attribute) in the same compilation, *Al.exe* will first try the container specified with **/keyname**. If that succeeds, the assembly is signed with the information in the key container. If *Al.exe* does not find the key container, it will try the file specified with **/keyfile**. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to the -i option in [*Sn.exe*](sn-exe-strong-name-tool.md)) so that on the next compilation, the **/keyname** option will be valid.| +|**/keyn[ame]:** `text`|Specifies a container that holds a key pair. This will sign the assembly (give it a strong name) by inserting a public key into the assembly manifest. *Al.exe* will then sign the final assembly with the private key.

Use *Sn.exe* to generate a key pair.

The key information appears in the .publickey field of the assembly.

Place `text` in double quotation marks (" ") if there is an embedded space.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/main:** `method`|Specifies the fully qualified name (`class`.`method`) of the method to use as an entry point when converting a module to an executable file.| |**/nologo**|Suppresses the banner, or logo, displayed at the command line when you invoke *Al.exe*.| |**/out:** `filename`|Specifies the name of the file produced by *Al.exe*. This is a required option.| |**/platform:** `text`|Limits which platform this code can run on; must be one of x86, Itanium, x64, anycpu (the default), or anycpu32bitpreferred.| -|**/prod[uct]:** `text`|Specifies a string for the **Product** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/product** appears in File Explorer as the Win32 **Product Name** resource.

If text is an empty string, the Win32 **Product Name** resource appears as a single space.

If you specify **/win32res**, **/product** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/productv[ersion]:** `text`|Specifies a string for the **Product Version** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/productversion** will be used as the Win32 **Product Version** resource. If you do not specify **/productversion**, the Win32 **Product Version** resource will be populated by the Win32 **File Version** resource.

If you specify **/win32res**, **/productversion** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/prod[uct]:** `text`|Specifies a string for the **Product** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/product** appears in File Explorer as the Win32 **Product Name** resource.

If text is an empty string, the Win32 **Product Name** resource appears as a single space.

If you specify **/win32res**, **/product** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/productv[ersion]:** `text`|Specifies a string for the **Product Version** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/productversion** will be used as the Win32 **Product Version** resource. If you do not specify **/productversion**, the Win32 **Product Version** resource will be populated by the Win32 **File Version** resource.

If you specify **/win32res**, **/productversion** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/t[arget]:** `lib[rary]` | `exe` | `win[exe]`|Specifies the file format of the output file: `lib[rary]` (code library), `exe` (console application), or `win[exe]` (Windows-based application). The default is `lib[rary]`.| |**/template:** `filename`|Specifies the assembly, `filename`, from which to inherit all assembly metadata, except the culture field.

An assembly that you create with **/template** will be a satellite assembly.| -|**/title:** `text`|Specifies a string for the **Title** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/title** appears in File Explorer as the Win32 **Description** resource, which is used by the shell as the friendly name of an application. It is also displayed on the **Open With** submenu of the shortcut menu for a file type for which there are multiple supporting applications.

If text is an empty string, the Win32 **Description** resource appears as a single space.

If you specify **/win32res**, **/title** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/trade[mark]:** `text`|Specifies a string for the **Trademark** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/trademark** appears in File Explorer as the Win32 **Trademark** resource.

If text is an empty string, the Win32 **Trademark** resource appears as a single space.

If you specify **/win32res**, **/trademark** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| -|**/v[ersion]:** `version`|Specifies version information for this assembly. The format of the version string is `major`.`minor`.`build`.`revision`. The default value is 0.

If you do specify **/version**, you must specify `major`. If you specify `major` and `minor`, you can specify an asterisk (\*)for `build`. This causes `build` to be equal to the number of days since January 1, 2000, local time, and `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

If you specify `major`, `minor`, and `build`, you can specify an asterisk for `revision`. This causes `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

To summarize, the valid version strings are as follows:

X

X.X

X.X.\*

X.X.X

X.X.X.\*

X.X.X.X

where X is any unsigned short constant except 65535 (0-65534).

If you do not specify **/win32res**, **/version** will be used as the Win32 **Assembly Version** resource.

If you do not specify **/win32res**, **/productversion**, and **/fileversion**, **/version** will be used for the **Assembly Version**, File Version, and **Product Version** Win32 resources.

If you specify **/win32res**, **/version** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any MSIL module.| +|**/title:** `text`|Specifies a string for the **Title** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/title** appears in File Explorer as the Win32 **Description** resource, which is used by the shell as the friendly name of an application. It is also displayed on the **Open With** submenu of the shortcut menu for a file type for which there are multiple supporting applications.

If text is an empty string, the Win32 **Description** resource appears as a single space.

If you specify **/win32res**, **/title** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/trade[mark]:** `text`|Specifies a string for the **Trademark** field in the assembly. Place the string in double quotation marks (" ") if `text` contains a space. This string is a custom attribute on the assembly and is available for viewing with reflection.

If you do not specify **/win32res**, **/trademark** appears in File Explorer as the Win32 **Trademark** resource.

If text is an empty string, the Win32 **Trademark** resource appears as a single space.

If you specify **/win32res**, **/trademark** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| +|**/v[ersion]:** `version`|Specifies version information for this assembly. The format of the version string is `major`.`minor`.`build`.`revision`. The default value is 0.

If you do specify **/version**, you must specify `major`. If you specify `major` and `minor`, you can specify an asterisk (\*)for `build`. This causes `build` to be equal to the number of days since January 1, 2000, local time, and `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

If you specify `major`, `minor`, and `build`, you can specify an asterisk for `revision`. This causes `revision` to be equal to the number of seconds since midnight of the current day, local time, divided by 2.

To summarize, the valid version strings are as follows:

X

X.X

X.X.\*

X.X.X

X.X.X.\*

X.X.X.X

where X is any unsigned short constant except 65535 (0-65534).

If you do not specify **/win32res**, **/version** will be used as the Win32 **Assembly Version** resource.

If you do not specify **/win32res**, **/productversion**, and **/fileversion**, **/version** will be used for the **Assembly Version**, File Version, and **Product Version** Win32 resources.

If you specify **/win32res**, **/version** will not affect the Win32 resource information.

You can also specify this option as a custom attribute () in the source code for any CIL module.| |**/win32icon:** `filename`|Inserts an .ico file in the assembly. The .ico file gives the output file the desired appearance in File Explorer.| |**/win32res:** `filename`|Inserts a Win32 resource (.res file) in the output file. A Win32 resource file can be created by using the Resource Compiler. The Resource Compiler is invoked when you compile a Visual C++ program; a .res file is created from the .rc file.| |`@filename`|Specifies a response file that contains *Al.exe* commands.

Commands in the response file can appear one per line or on the same line, separated by one or more spaces.| diff --git a/docs/framework/tools/index.md b/docs/framework/tools/index.md index 093ddfc14f847..f4cc2f8bdb8ab 100644 --- a/docs/framework/tools/index.md +++ b/docs/framework/tools/index.md @@ -82,7 +82,7 @@ Enables you to tune native image assemblies using common end-user scenarios. Mpg Improves the performance of managed applications through the use of native images (files containing compiled processor-specific machine code). The runtime can use native images from the cache instead of using the just-in-time (JIT) compiler to compile the original assembly. [Peverify.exe (PEVerify Tool)](peverify-exe-peverify-tool.md)\ -Helps you verify whether your Microsoft intermediate language (MSIL) code and associated metadata meet type safety requirements. +Helps you verify whether your common intermediate language (CIL) code and associated metadata meet type safety requirements. [Regasm.exe (Assembly Registration Tool)](regasm-exe-assembly-registration-tool.md)\ Reads the metadata within an assembly and adds the necessary entries to the registry. This enables COM clients to appear as .NET Framework classes. diff --git a/docs/framework/tools/installutil-exe-installer-tool.md b/docs/framework/tools/installutil-exe-installer-tool.md index 653749a7bac54..16dde69b7bc21 100644 --- a/docs/framework/tools/installutil-exe-installer-tool.md +++ b/docs/framework/tools/installutil-exe-installer-tool.md @@ -83,7 +83,7 @@ Installutil.exe uses reflection to inspect the specified assemblies and to find Installutil.exe cannot install or uninstall delay-signed assemblies, but it can install or uninstall strong-named assemblies. -Starting with .NET Framework version 2.0, the 32-bit version of the common language runtime (CLR) ships with only the 32-bit version of the Installer tool, but the 64-bit version of the CLR ships with both 32-bit and 64-bit versions of the Installer tool. When using the 64-bit CLR, use the 32-bit Installer tool to install 32-bit assemblies, and the 64-bit Installer tool to install 64-bit and Microsoft intermediate language (MSIL) assemblies. Both versions of the Installer tool behave the same. +Starting with .NET Framework version 2.0, the 32-bit version of the common language runtime (CLR) ships with only the 32-bit version of the Installer tool, but the 64-bit version of the CLR ships with both 32-bit and 64-bit versions of the Installer tool. When using the 64-bit CLR, use the 32-bit Installer tool to install 32-bit assemblies, and the 64-bit Installer tool to install 64-bit and common intermediate language (CIL) assemblies. Both versions of the Installer tool behave the same. You cannot use Installutil.exe to deploy a Windows service that was created by using C++, because Installutil.exe cannot recognize the embedded native code that is produced by the C++ compiler. If you try to deploy a C++ Windows service with Installutil.exe, an exception such as will be thrown. To work with this scenario, move the service code to a C++ module, and then write the installer object in C# or Visual Basic. diff --git a/docs/framework/tools/mdbg-exe.md b/docs/framework/tools/mdbg-exe.md index 6a24725965235..05bd997528bc5 100644 --- a/docs/framework/tools/mdbg-exe.md +++ b/docs/framework/tools/mdbg-exe.md @@ -2,104 +2,104 @@ title: "MDbg.exe (.NET Framework Command-Line Debugger)" description: Understand MDbg.exe, the command-line debugger for .NET, which helps tools vendors and application developers find and fix bugs in programs targeting the CLR. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "command-line debugger [.NET Framework]" - "MDbg.exe" ms.assetid: 28a3f509-07e2-4dbe-81df-874c5e969cc4 --- # MDbg.exe (.NET Framework Command-Line Debugger) -The NET Framework Command-Line Debugger helps tools vendors and application developers find and fix bugs in programs that target the .NET Framework common language runtime. This tool uses the runtime debugging API to provide debugging services. You can use MDbg.exe to debug only managed code; there is no support for debugging unmanaged code. - +The NET Framework Command-Line Debugger helps tools vendors and application developers find and fix bugs in programs that target the .NET Framework common language runtime. This tool uses the runtime debugging API to provide debugging services. You can use MDbg.exe to debug only managed code; there is no support for debugging unmanaged code. + This tool is available through NuGet. For installation information, see [MDbg 0.1.0](https://www.nuget.org/packages/MDbg/0.1.0). To run the tool, use the Package Manager Console. For more information about how to use the Package Manager Console, see the [Package Manager Console](/nuget/tools/package-manager-console) article. - -At the Package Manager prompt, type the following: - -## Syntax - -```console -MDbg [ProgramName[arguments]] [options] -``` - -## Commands - - When you are in the debugger (as indicated by the **mdbg>** prompt), type one of the commands described in the next section: - - **command** [*arguments*] - - MDbg.exe commands are case-sensitive. - -|Command|Description| -|-------------|-----------------| -|**ap**[**rocess**] [*number*]|Switches to another debugged process or prints available processes. The numbers are not real process IDs (PIDs), but a 0-indexed list.| -|**a**[**ttach**] [*pid*]|Attaches to a process or prints available processes.| -|**b**[**reak**] [*ClassName.Method* | *FileName:LineNo*]|Sets a breakpoint at the specified method. Modules are scanned sequentially.

- **break** *FileName:LineNo* sets a breakpoint at a location in the source.
- **break** *~number* sets a breakpoint on a symbol recently displayed with the **x** command.
- **break** *module!ClassName.Method+IlOffset* sets a breakpoint on the fully qualified location.| -|**block**[**ingObjects**]|Displays monitor locks, which are blocking threads.| -|**ca**[**tch**] [*exceptionType*]|Causes the debugger to break on all exceptions, and not just on the unhandled exceptions.| -|**cl**[**earException**]|Marks the current exception as handled so that execution can continue. If the cause of the exception has not been dealt with, the exception may be quickly rethrown.| -|**conf**[**ig**] [*option value*]|Displays all configurable options and shows how the options are invoked without any optional values. If the option is specified, sets `value` as the current option. The following options are currently available:

- `extpath` sets the path to search for extensions when the `load` command is used.
- `extpath+` adds a path for loading extensions.| -|**del**[**ete**]|Deletes a breakpoint.| -|**de**[**tach**]|Detaches from a debugged process.| -|**d**[**own**] [*frames*]|Moves the active stack frame down.| -|**echo**|Echoes a message to the console.| -|**enableNotif**[**ication**] *typeName* 0|1|Enables (1) or disables (0) custom notifications for the specified type.| -|**ex**[**it**] [*exitcode*]|Exits the MDbg.exe shell, and optionally specifies the process exit code.| -|**fo**[**reach**] [*OtherCommand*]|Performs a command on all threads. *OtherCommand* is a valid command that operates on one thread; **foreach** *OtherCommand* performs the same command on all threads.| -|**f**[**unceval**] [`-ad` *Num*] *functionName* [*args ...* ]|Performs a function evaluation on the current active thread where the function to evaluate is *functionName*. The function name must be fully qualified, including namespaces.

The `-ad` option specifies the application domain to use to resolve the function. If the `-ad` option is not specified, the application domain for resolution defaults to the application domain where the thread that is used for function evaluation is located.

If the function that is being evaluated is not static, the first parameter passed in should be a `this` pointer. All application domains are searched for arguments to the function evaluation..

To request a value from an application domain, prefix the variable with the module and application domain name; for example, `funceval -ad 0 System.Object.ToString hello.exe#0!MyClass.g_rootRef`. This command evaluates the function `System.Object.ToString` in the application domain `0`. Because the `ToString` method is an instance function, the first parameter must be a `this` pointer.| -|**g**[**o**]|Causes the program to continue until it encounters a breakpoint, the program exits, or an event (for example, an unhandled exception) causes the program to stop.| -|**h**[**elp**] [*command*]

-or-

**?** [*command*]|Displays a description of all commands or a detailed description of a specified command.| -|**ig**[**nore**] [*event*]|Causes the debugger to stop on unhandled exceptions only.| -|**int**[**ercept**] *FrameNumber*|Rolls the debugger back to a specified frame number.

If the debugger encounters an exception, use this command to roll the debugger back to the specified frame number. You can change the program state by using the **set** command and continue by using the **go** command.| -|**k**[**ill**]|Stops the active process.| -|**l**[**ist**] [*modules* | *appdomains* | *assemblies*]|Displays the loaded modules, application domains, or assemblies.| -|**lo**[**ad**] *assemblyName*|Loads an extension in the following manner: The specified assembly is loaded and an attempt is then made to run the static method `LoadExtension` from the `Microsoft.Tools.Mdbg.Extension.Extension` type.| -|**log** [*eventType*]|Set or display the events to be logged.| -|**mo**[**de**] [*option on/off*]|Sets different debugger options. Use `mode` with no options to get a list of the debugging modes and their current settings.| -|**mon**[**itorInfo**] *monitorReference*|Displays object monitor lock information.| -|**newo**[**bj**] *typeName* [*arguments...*]|Creates a new object of type *typeName*.| -|**n**[**ext**]|Runs code and moves to the next line (even if the next line includes many function calls).| -|**Opendump** *pathToDumpFile*|Opens the specified dump file for debugging.| -|**o**[**ut**]|Moves to the end of the current function.| -|**pa**[**th**] [*pathName*]|Searches the specified path for the source files if the location in the binaries is not available.| -|**p**[**rint**] [*var*] | [`-d`]|Prints all variables in scope (**print**), prints the specified variable (**print** *var*), or prints the debugger variables (**print**`-d`).| -|**printe**[**xception**] [*-r*]|Prints the last exception on the current thread. Use the `–r` (recursive) option to traverse the `InnerException` property on the exception object to get information about the entire chain of exceptions.| -|**pro**[**cessenum**]|Displays the active processes.| -|**q**[**uit**] [*exitcode*]|Quits the MDbg.exe shell, optionally specifying the process exit code.| -|**re**[**sume**] [`*` | [`~`]*threadNumber*]|Resumes the current thread or the thread specified by the *threadNumber* parameter.

If the *threadNumber* parameter is specified as `*` or if the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*.

Resuming a non-suspended thread has no effect.| -|**r**[**un**] [`-d`(`ebug`) | -`o`(`ptimize`) |`-enc`] [[*path_to_exe*] [*args_to_exe*]]|Stops the current process (if there is one) and starts a new one. If no executable argument is passed, this command runs the program that was previously executed with the `run` command. If the executable argument is provided, the specified program is run using the optionally supplied arguments.

If class load, module load, and thread start events are ignored (as they are by default), the program stops on the first executable instruction of the main thread.

You can force the debugger to just-in-time (JIT) compile the code by using one of the following three flags:

- `-d` *(* `ebug` *)* disables optimizations. This is the default for MDbg.exe.
- `-o` *(* `ptimize` *)* forces the code to run more like it does outside the debugger, but also makes the debugging experience more difficult. This is the default for use outside the debugger.
- `-enc` enables the Edit and Continue feature but incurs a performance hit.| -|**Set** *variable*=*value*|Changes the value of any in-scope variable.

You can also create your own debugger variables and assign reference values to them from within your application. These values act as handles to the original value, and even the original value is out of scope. All debugger variables must begin with `$` (for example, `$var`). Clear these handles by setting them to nothing using the following command:

`set $var=`| -|**Setip** [`-il`] *number*|Sets the current instruction pointer (IP) in the file to the specified position. If you specify the `-il` option, the number represents a Microsoft intermediate language (MSIL) offset in the method. Otherwise, the number represents a source line number.| -|**sh**[**ow**] [*lines*]|Specifies the number of lines to show.| -|**s**[**tep**]|Moves execution into the next function on the current line, or moves to the next line if there is no function to step into.| -|**su**[**spend**] [\* | [~]*threadNumber*]|Suspends the current thread or the thread specified by the *threadNumber* parameter. If *threadNumber* is specified as `*`, the command applies to all threads. If the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*. Suspended threads are excluded from running when the process is run by either the **go** or **step** command. If there are no non-suspended threads in the process and you issue the **go** command, the process will not continue. In that case, press CTRL-C to break into the process.| -|**sy**[**mbol**] *commandName* [*commandValue*]|Specifies one of the following commands:

- `symbol path` [`"value"`] - Displays or sets the current symbol path.
- `symbol addpath` `"value"` - Adds to your current symbol path.
- `symbol reload` [`"module"`] - Reloads either all symbols or the symbols for the specified module.
- `symbol list` [`module`] - Shows the currently loaded symbols for either all modules or the specified module.| -|**t**[**hread**] [*newThread*] [-*nick nickname*`]`|The thread command with no parameters displays all managed threads in the current process. Threads are usually identified by their thread numbers; however, if the thread has an assigned nickname, the nickname is displayed instead. You can use the `-nick` parameter to assign a nickname to a thread.

- **thread** `-nick` *threadName* assigns a nickname to the currently running thread.

Nicknames cannot be numbers. If the current thread already has an assigned nickname, the old nickname is replaced with the new one. If the new nickname is an empty string (""), the nickname for the current thread is deleted and no new nickname is assigned to the thread.| -|**u**[**p**]|Moves the active stack frame up.| -|**uwgc**[**handle**] [*var*] | [*address*]|Prints the variable tracked by a handle. The handle can be specified by name or address.| -|**when**|Displays the currently active `when` statements.

**when** **delete all** | `num` [`num` [`num` …]] - Deletes the `when` statement specified by the number, or all `when` statements if `all` is specified.

**when** `stopReason` [`specific_condition`] **do**`cmd` [`cmd` [`cmd` …] ] - The *stopReason* parameter can be one of the following:

`StepComplete`, `ProcessExited`, `ThreadCreated`, `BreakpointHit`, `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ControlCTrapped`, `ExceptionThrown`, `UnhandledExceptionThrown`, `AsyncStop`, `AttachComplete`, `UserBreak`, `EvalComplete`, `EvalException`, `RemapOpportunityReached`, `NativeStop`.

*specific_condition* can be one of the following:

- *number* - For `ThreadCreated` and `BreakpointHit`, triggers action only when stopped by a thread ID/breakpoint number with same value.
- [`!`]*name* - For `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ExceptionThrown`, and `UnhandledExceptionThrown`, triggers action only when the name matches the name of the *stopReason*.

*specific_condition* must be empty for other values of *stopReason*.| -|**w**[**here**] [`-v`] [`-c` *depth*] [*threadID*]|Displays debug information about stack frames.

- The `-v` option provides verbose information about each displayed stack frame.
- Specifying a number for `depth` limits how many frames are displayed. Use the **all** command to display all frames. The default is 100.
- If you specify the *threadID* parameter, you can control which thread is associated with the stack. The default is the current thread only. Use the **all** command to get all threads.| -|**x** [`-c`*numSymbols*] [*module*[`!`*pattern*]]|Displays functions that match the `pattern` for a module.

If *numSymbols* is specified, the output is limited to the specified number. If `!` (indicating a regular expression) is not specified for *pattern*, all functions are displayed. If *module* is not provided, all loaded modules are displayed. Symbols (*~#*) can be used to set breakpoints using the **break** command.| - -## Remarks - - Compile the application to be debugged by using compiler-specific flags that cause your compiler to generate debugging symbols. Refer to your compiler's documentation for more information about these flags. You can debug optimized applications, but some debugging information will be missing. For example, many local variables will not be visible and source lines will be inaccurate. - - After you compile your application, type **mdbg** at the command prompt to start a debugging session, as shown in the following example. - -```console -C:\Program Files\Microsoft Visual Studio 8\VC>mdbg -MDbg (Managed debugger) v2.0.50727.42 (RTM.050727-4200) started. -Copyright (C) Microsoft Corporation. All rights reserved. - -For information about commands type "help"; -to exit program type "quit". -mdbg> -``` - - The `mdbg>` prompt indicates that you are in the debugger. - - Once you are in the debugger, use the commands and arguments described in the previous section. - + +At the Package Manager prompt, type the following: + +## Syntax + +```console +MDbg [ProgramName[arguments]] [options] +``` + +## Commands + + When you are in the debugger (as indicated by the **mdbg>** prompt), type one of the commands described in the next section: + + **command** [*arguments*] + + MDbg.exe commands are case-sensitive. + +|Command|Description| +|-------------|-----------------| +|**ap**[**rocess**] [*number*]|Switches to another debugged process or prints available processes. The numbers are not real process IDs (PIDs), but a 0-indexed list.| +|**a**[**ttach**] [*pid*]|Attaches to a process or prints available processes.| +|**b**[**reak**] [*ClassName.Method* | *FileName:LineNo*]|Sets a breakpoint at the specified method. Modules are scanned sequentially.

- **break** *FileName:LineNo* sets a breakpoint at a location in the source.
- **break** *~number* sets a breakpoint on a symbol recently displayed with the **x** command.
- **break** *module!ClassName.Method+IlOffset* sets a breakpoint on the fully qualified location.| +|**block**[**ingObjects**]|Displays monitor locks, which are blocking threads.| +|**ca**[**tch**] [*exceptionType*]|Causes the debugger to break on all exceptions, and not just on the unhandled exceptions.| +|**cl**[**earException**]|Marks the current exception as handled so that execution can continue. If the cause of the exception has not been dealt with, the exception may be quickly rethrown.| +|**conf**[**ig**] [*option value*]|Displays all configurable options and shows how the options are invoked without any optional values. If the option is specified, sets `value` as the current option. The following options are currently available:

- `extpath` sets the path to search for extensions when the `load` command is used.
- `extpath+` adds a path for loading extensions.| +|**del**[**ete**]|Deletes a breakpoint.| +|**de**[**tach**]|Detaches from a debugged process.| +|**d**[**own**] [*frames*]|Moves the active stack frame down.| +|**echo**|Echoes a message to the console.| +|**enableNotif**[**ication**] *typeName* 0|1|Enables (1) or disables (0) custom notifications for the specified type.| +|**ex**[**it**] [*exitcode*]|Exits the MDbg.exe shell, and optionally specifies the process exit code.| +|**fo**[**reach**] [*OtherCommand*]|Performs a command on all threads. *OtherCommand* is a valid command that operates on one thread; **foreach** *OtherCommand* performs the same command on all threads.| +|**f**[**unceval**] [`-ad` *Num*] *functionName* [*args ...* ]|Performs a function evaluation on the current active thread where the function to evaluate is *functionName*. The function name must be fully qualified, including namespaces.

The `-ad` option specifies the application domain to use to resolve the function. If the `-ad` option is not specified, the application domain for resolution defaults to the application domain where the thread that is used for function evaluation is located.

If the function that is being evaluated is not static, the first parameter passed in should be a `this` pointer. All application domains are searched for arguments to the function evaluation..

To request a value from an application domain, prefix the variable with the module and application domain name; for example, `funceval -ad 0 System.Object.ToString hello.exe#0!MyClass.g_rootRef`. This command evaluates the function `System.Object.ToString` in the application domain `0`. Because the `ToString` method is an instance function, the first parameter must be a `this` pointer.| +|**g**[**o**]|Causes the program to continue until it encounters a breakpoint, the program exits, or an event (for example, an unhandled exception) causes the program to stop.| +|**h**[**elp**] [*command*]

-or-

**?** [*command*]|Displays a description of all commands or a detailed description of a specified command.| +|**ig**[**nore**] [*event*]|Causes the debugger to stop on unhandled exceptions only.| +|**int**[**ercept**] *FrameNumber*|Rolls the debugger back to a specified frame number.

If the debugger encounters an exception, use this command to roll the debugger back to the specified frame number. You can change the program state by using the **set** command and continue by using the **go** command.| +|**k**[**ill**]|Stops the active process.| +|**l**[**ist**] [*modules* | *appdomains* | *assemblies*]|Displays the loaded modules, application domains, or assemblies.| +|**lo**[**ad**] *assemblyName*|Loads an extension in the following manner: The specified assembly is loaded and an attempt is then made to run the static method `LoadExtension` from the `Microsoft.Tools.Mdbg.Extension.Extension` type.| +|**log** [*eventType*]|Set or display the events to be logged.| +|**mo**[**de**] [*option on/off*]|Sets different debugger options. Use `mode` with no options to get a list of the debugging modes and their current settings.| +|**mon**[**itorInfo**] *monitorReference*|Displays object monitor lock information.| +|**newo**[**bj**] *typeName* [*arguments...*]|Creates a new object of type *typeName*.| +|**n**[**ext**]|Runs code and moves to the next line (even if the next line includes many function calls).| +|**Opendump** *pathToDumpFile*|Opens the specified dump file for debugging.| +|**o**[**ut**]|Moves to the end of the current function.| +|**pa**[**th**] [*pathName*]|Searches the specified path for the source files if the location in the binaries is not available.| +|**p**[**rint**] [*var*] | [`-d`]|Prints all variables in scope (**print**), prints the specified variable (**print** *var*), or prints the debugger variables (**print**`-d`).| +|**printe**[**xception**] [*-r*]|Prints the last exception on the current thread. Use the `–r` (recursive) option to traverse the `InnerException` property on the exception object to get information about the entire chain of exceptions.| +|**pro**[**cessenum**]|Displays the active processes.| +|**q**[**uit**] [*exitcode*]|Quits the MDbg.exe shell, optionally specifying the process exit code.| +|**re**[**sume**] [`*` | [`~`]*threadNumber*]|Resumes the current thread or the thread specified by the *threadNumber* parameter.

If the *threadNumber* parameter is specified as `*` or if the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*.

Resuming a non-suspended thread has no effect.| +|**r**[**un**] [`-d`(`ebug`) | -`o`(`ptimize`) |`-enc`] [[*path_to_exe*] [*args_to_exe*]]|Stops the current process (if there is one) and starts a new one. If no executable argument is passed, this command runs the program that was previously executed with the `run` command. If the executable argument is provided, the specified program is run using the optionally supplied arguments.

If class load, module load, and thread start events are ignored (as they are by default), the program stops on the first executable instruction of the main thread.

You can force the debugger to just-in-time (JIT) compile the code by using one of the following three flags:

- `-d` *(* `ebug` *)* disables optimizations. This is the default for MDbg.exe.
- `-o` *(* `ptimize` *)* forces the code to run more like it does outside the debugger, but also makes the debugging experience more difficult. This is the default for use outside the debugger.
- `-enc` enables the Edit and Continue feature but incurs a performance hit.| +|**Set** *variable*=*value*|Changes the value of any in-scope variable.

You can also create your own debugger variables and assign reference values to them from within your application. These values act as handles to the original value, and even the original value is out of scope. All debugger variables must begin with `$` (for example, `$var`). Clear these handles by setting them to nothing using the following command:

`set $var=`| +|**Setip** [`-il`] *number*|Sets the current instruction pointer (IP) in the file to the specified position. If you specify the `-il` option, the number represents a common intermediate language (CIL) offset in the method. Otherwise, the number represents a source line number.| +|**sh**[**ow**] [*lines*]|Specifies the number of lines to show.| +|**s**[**tep**]|Moves execution into the next function on the current line, or moves to the next line if there is no function to step into.| +|**su**[**spend**] [\* | [~]*threadNumber*]|Suspends the current thread or the thread specified by the *threadNumber* parameter. If *threadNumber* is specified as `*`, the command applies to all threads. If the thread number starts with `~`, the command applies to all threads except the one specified by *threadNumber*. Suspended threads are excluded from running when the process is run by either the **go** or **step** command. If there are no non-suspended threads in the process and you issue the **go** command, the process will not continue. In that case, press CTRL-C to break into the process.| +|**sy**[**mbol**] *commandName* [*commandValue*]|Specifies one of the following commands:

- `symbol path` [`"value"`] - Displays or sets the current symbol path.
- `symbol addpath` `"value"` - Adds to your current symbol path.
- `symbol reload` [`"module"`] - Reloads either all symbols or the symbols for the specified module.
- `symbol list` [`module`] - Shows the currently loaded symbols for either all modules or the specified module.| +|**t**[**hread**] [*newThread*] [-*nick nickname*`]`|The thread command with no parameters displays all managed threads in the current process. Threads are usually identified by their thread numbers; however, if the thread has an assigned nickname, the nickname is displayed instead. You can use the `-nick` parameter to assign a nickname to a thread.

- **thread** `-nick` *threadName* assigns a nickname to the currently running thread.

Nicknames cannot be numbers. If the current thread already has an assigned nickname, the old nickname is replaced with the new one. If the new nickname is an empty string (""), the nickname for the current thread is deleted and no new nickname is assigned to the thread.| +|**u**[**p**]|Moves the active stack frame up.| +|**uwgc**[**handle**] [*var*] | [*address*]|Prints the variable tracked by a handle. The handle can be specified by name or address.| +|**when**|Displays the currently active `when` statements.

**when** **delete all** | `num` [`num` [`num` …]] - Deletes the `when` statement specified by the number, or all `when` statements if `all` is specified.

**when** `stopReason` [`specific_condition`] **do**`cmd` [`cmd` [`cmd` …] ] - The *stopReason* parameter can be one of the following:

`StepComplete`, `ProcessExited`, `ThreadCreated`, `BreakpointHit`, `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ControlCTrapped`, `ExceptionThrown`, `UnhandledExceptionThrown`, `AsyncStop`, `AttachComplete`, `UserBreak`, `EvalComplete`, `EvalException`, `RemapOpportunityReached`, `NativeStop`.

*specific_condition* can be one of the following:

- *number* - For `ThreadCreated` and `BreakpointHit`, triggers action only when stopped by a thread ID/breakpoint number with same value.
- [`!`]*name* - For `ModuleLoaded`, `ClassLoaded`, `AssemblyLoaded`, `AssemblyUnloaded`, `ExceptionThrown`, and `UnhandledExceptionThrown`, triggers action only when the name matches the name of the *stopReason*.

*specific_condition* must be empty for other values of *stopReason*.| +|**w**[**here**] [`-v`] [`-c` *depth*] [*threadID*]|Displays debug information about stack frames.

- The `-v` option provides verbose information about each displayed stack frame.
- Specifying a number for `depth` limits how many frames are displayed. Use the **all** command to display all frames. The default is 100.
- If you specify the *threadID* parameter, you can control which thread is associated with the stack. The default is the current thread only. Use the **all** command to get all threads.| +|**x** [`-c`*numSymbols*] [*module*[`!`*pattern*]]|Displays functions that match the `pattern` for a module.

If *numSymbols* is specified, the output is limited to the specified number. If `!` (indicating a regular expression) is not specified for *pattern*, all functions are displayed. If *module* is not provided, all loaded modules are displayed. Symbols (*~#*) can be used to set breakpoints using the **break** command.| + +## Remarks + + Compile the application to be debugged by using compiler-specific flags that cause your compiler to generate debugging symbols. Refer to your compiler's documentation for more information about these flags. You can debug optimized applications, but some debugging information will be missing. For example, many local variables will not be visible and source lines will be inaccurate. + + After you compile your application, type **mdbg** at the command prompt to start a debugging session, as shown in the following example. + +```console +C:\Program Files\Microsoft Visual Studio 8\VC>mdbg +MDbg (Managed debugger) v2.0.50727.42 (RTM.050727-4200) started. +Copyright (C) Microsoft Corporation. All rights reserved. + +For information about commands type "help"; +to exit program type "quit". +mdbg> +``` + + The `mdbg>` prompt indicates that you are in the debugger. + + Once you are in the debugger, use the commands and arguments described in the previous section. + ## See also - [Tools](index.md) diff --git a/docs/framework/tools/ngen-exe-native-image-generator.md b/docs/framework/tools/ngen-exe-native-image-generator.md index 047a2b4d49aee..8d09aff619f01 100644 --- a/docs/framework/tools/ngen-exe-native-image-generator.md +++ b/docs/framework/tools/ngen-exe-native-image-generator.md @@ -237,13 +237,13 @@ Hard binding can affect startup time, because all images that are hard bound to The following general considerations and application considerations may assist you in deciding whether to undertake the effort of evaluating native images for your application: -- Native images load faster than MSIL because they eliminate the need for many startup activities, such as JIT compilation and type-safety verification. +- Native images load faster than CIL because they eliminate the need for many startup activities, such as JIT compilation and type-safety verification. - Native images require a smaller initial working set because there is no need for the JIT compiler. - Native images enable code sharing between processes. -- Native images require more hard disk space than MSIL assemblies and may require considerable time to generate. +- Native images require more hard disk space than CIL assemblies and may require considerable time to generate. - Native images must be maintained. diff --git a/docs/framework/tools/peverify-exe-peverify-tool.md b/docs/framework/tools/peverify-exe-peverify-tool.md index 963bbde422e46..9ddbd3210af2f 100644 --- a/docs/framework/tools/peverify-exe-peverify-tool.md +++ b/docs/framework/tools/peverify-exe-peverify-tool.md @@ -1,8 +1,8 @@ --- title: "Peverify.exe (PEVerify Tool)" -description: Use Peverify.exe (portable executable verify) to help determine if Microsoft intermediate language (MSIL) code & metadata meet type safety standards in .NET. +description: Use Peverify.exe (portable executable verify) to help determine if MSIL code & metadata meet type safety standards in .NET. ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "portable executable files, PEVerify" - "verifying MSIL and metadata" - "PEVerify tool" @@ -14,106 +14,106 @@ ms.assetid: f4f46f9e-8d08-4e66-a94b-0c69c9b0bbfa --- # Peverify.exe (PEVerify tool) -The PEVerify tool helps developers who generate Microsoft intermediate language (MSIL) (such as compiler writers and script engine developers) to determine whether their MSIL code and associated metadata meet type safety requirements. Some compilers generate verifiably type-safe code only if you avoid using certain language constructs. If you're using such a compiler, you may want to verify that you have not compromised the type safety of your code. You can run the PEVerify tool on your files to check the MSIL and metadata. - +The PEVerify tool helps developers who generate Microsoft intermediate language (MSIL) (such as compiler writers and script engine developers) to determine whether their MSIL code and associated metadata meet type safety requirements. Some compilers generate verifiably type-safe code only if you avoid using certain language constructs. If you're using such a compiler, you may want to verify that you have not compromised the type safety of your code. You can run the PEVerify tool on your files to check the MSIL and metadata. + This tool is automatically installed with Visual Studio. To run the tool, use [Visual Studio Developer Command Prompt or Visual Studio Developer PowerShell](/visualstudio/ide/reference/command-prompt-powershell). - -## Syntax - -```console -peverify filename [options] -``` - -## Parameters - -|Argument|Description| -|--------------|-----------------| -|*filename*|The portable executable (PE) file for which to check the MSIL and metadata.| - -|Option|Description| -|------------|-----------------| -|**/break=** *maxErrorCount*|Aborts verification after *maxErrorCount* errors.

This parameter is not supported in .NET Framework version 2.0 or later.| -|**/clock**|Measures and reports the following verification times in milliseconds:

**MD Val. cycle**
Metadata validation cycle

**MD Val. pure**
Metadata validation pure

**IL Ver. cycle**
Microsoft intermediate language (MSIL) verification cycle

**IL Ver pure**
MSIL verification pure

The **MD Val. cycle** and **IL Ver. cycle** times include the time required to perform necessary startup and shutdown procedures. The **MD Val. pure** and **IL Ver pure** times reflect the time required to perform the validation or verification only.| -|**/help**|Displays command syntax and options for the tool.| -|**/hresult**|Displays error codes in hexadecimal format.| -|**/ignore=** *hex.code* [, *hex.code*]|Ignores the specified error codes.| -|**/ignore=@** *responseFile*|Ignores the error codes listed in the specified response file.| -|**/il**|Performs MSIL type safety verification checks for methods implemented in the assembly specified by *filename*. The tool returns detailed descriptions for each problem found unless you specify the **/quiet** option.| -|**/md**|Performs metadata validation checks on the assembly specified by *filename*. This option walks the full metadata structure within the file and reports all validation problems encountered.| -|**/nologo**|Suppresses the display of product version and copyright information.| -|**/nosymbols**|In .NET Framework version 2.0, suppresses line numbers for backward compatibility.| -|**/quiet**|Specifies quiet mode; suppresses output of the verification problem reports. Peverify.exe still reports whether the file is type safe, but does not report information on problems preventing type safety verification.| -|`/transparent`|Verify only the transparent methods.| -|**/unique**|Ignores repeating error codes.| -|**/verbose**|In .NET Framework version 2.0, displays additional information in MSIL verification messages.| -|**/?**|Displays command syntax and options for the tool.| - -## Remarks - - The common language runtime relies on the type-safe execution of application code to help enforce security and isolation mechanisms. Normally, code that is not [verifiably type safe](../../standard/security/key-security-concepts.md#type-safety-and-security) cannot run, although you can set security policy to allow the execution of trusted but unverifiable code. - - If neither the **/md** nor **/il** options are specified, Peverify.exe performs both types of checks. Peverify.exe performs **/md** checks first. If there are no errors, **/il** checks are made. If you specify both **/md** and **/il**, **/il** checks are made even if there are errors in the metadata. Thus, if there are no metadata errors, **peverify** *filename* is equivalent to **peverify** *filename* **/md** **/il**. - - Peverify.exe performs comprehensive MSIL verification checks based on dataflow analysis plus a list of several hundred rules on valid metadata. For detailed information on the checks Peverify.exe performs, see the "Metadata Validation Specification" and the "MSIL Instruction Set Specification" in the Tools Developers Guide folder in the Windows SDK. - -.NET Framework version 2.0 or later supports verifiable `byref` returns specified using the following MSIL instructions: `dup`, `ldsflda`, `ldflda`, `ldelema`, `call`, and `unbox`. - -## Examples - - The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. - -```console -peverify myAssembly.exe /md /il -``` - - Upon successful completion of the above request, Peverify.exe displays the following message. - + +## Syntax + +```console +peverify filename [options] +``` + +## Parameters + +|Argument|Description| +|--------------|-----------------| +|*filename*|The portable executable (PE) file for which to check the MSIL and metadata.| + +|Option|Description| +|------------|-----------------| +|**/break=** *maxErrorCount*|Aborts verification after *maxErrorCount* errors.

This parameter is not supported in .NET Framework version 2.0 or later.| +|**/clock**|Measures and reports the following verification times in milliseconds:

**MD Val. cycle**
Metadata validation cycle

**MD Val. pure**
Metadata validation pure

**IL Ver. cycle**
Microsoft intermediate language (MSIL) verification cycle

**IL Ver pure**
MSIL verification pure

The **MD Val. cycle** and **IL Ver. cycle** times include the time required to perform necessary startup and shutdown procedures. The **MD Val. pure** and **IL Ver pure** times reflect the time required to perform the validation or verification only.| +|**/help**|Displays command syntax and options for the tool.| +|**/hresult**|Displays error codes in hexadecimal format.| +|**/ignore=** *hex.code* [, *hex.code*]|Ignores the specified error codes.| +|**/ignore=@** *responseFile*|Ignores the error codes listed in the specified response file.| +|**/il**|Performs MSIL type safety verification checks for methods implemented in the assembly specified by *filename*. The tool returns detailed descriptions for each problem found unless you specify the **/quiet** option.| +|**/md**|Performs metadata validation checks on the assembly specified by *filename*. This option walks the full metadata structure within the file and reports all validation problems encountered.| +|**/nologo**|Suppresses the display of product version and copyright information.| +|**/nosymbols**|In .NET Framework version 2.0, suppresses line numbers for backward compatibility.| +|**/quiet**|Specifies quiet mode; suppresses output of the verification problem reports. Peverify.exe still reports whether the file is type safe, but does not report information on problems preventing type safety verification.| +|`/transparent`|Verify only the transparent methods.| +|**/unique**|Ignores repeating error codes.| +|**/verbose**|In .NET Framework version 2.0, displays additional information in MSIL verification messages.| +|**/?**|Displays command syntax and options for the tool.| + +## Remarks + + The common language runtime relies on the type-safe execution of application code to help enforce security and isolation mechanisms. Normally, code that is not [verifiably type safe](../../standard/security/key-security-concepts.md#type-safety-and-security) cannot run, although you can set security policy to allow the execution of trusted but unverifiable code. + + If neither the **/md** nor **/il** options are specified, Peverify.exe performs both types of checks. Peverify.exe performs **/md** checks first. If there are no errors, **/il** checks are made. If you specify both **/md** and **/il**, **/il** checks are made even if there are errors in the metadata. Thus, if there are no metadata errors, **peverify** *filename* is equivalent to **peverify** *filename* **/md** **/il**. + + Peverify.exe performs comprehensive MSIL verification checks based on dataflow analysis plus a list of several hundred rules on valid metadata. For detailed information on the checks Peverify.exe performs, see the "Metadata Validation Specification" and the "MSIL Instruction Set Specification" in the Tools Developers Guide folder in the Windows SDK. + +.NET Framework version 2.0 or later supports verifiable `byref` returns specified using the following MSIL instructions: `dup`, `ldsflda`, `ldflda`, `ldelema`, `call`, and `unbox`. + +## Examples + + The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. + +```console +peverify myAssembly.exe /md /il +``` + + Upon successful completion of the above request, Peverify.exe displays the following message. + ```output -All classes and methods in myAssembly.exe Verified -``` - - The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. The tool displays the time required to perform these checks. - -```console -peverify myAssembly.exe /md /il /clock -``` - - Upon successful completion of the above request, Peverify.exe displays the following message. - +All classes and methods in myAssembly.exe Verified +``` + + The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. The tool displays the time required to perform these checks. + +```console +peverify myAssembly.exe /md /il /clock +``` + + Upon successful completion of the above request, Peverify.exe displays the following message. + ```output -All classes and methods in myAssembly.exe Verified -Timing: Total run 320 msec - MD Val.cycle 40 msec - MD Val.pure 10 msec - IL Ver.cycle 270 msec - IL Ver.pure 230 msec -``` - - The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. Peverify.exe stops, however, when it reaches the maximum error count of 100. The tool also ignores the specified error codes. - -```console -peverify myAssembly.exe /break=100 /ignore=0x12345678,0xABCD1234 -``` - - The following command produces the same result as the above previous example, but specifies the error codes to ignore in the response file `ignoreErrors.rsp`. - -```console -peverify myAssembly.exe /break=100 /ignore@ignoreErrors.rsp -``` - - The response file can contain a comma-separated list of error codes. - +All classes and methods in myAssembly.exe Verified +Timing: Total run 320 msec + MD Val.cycle 40 msec + MD Val.pure 10 msec + IL Ver.cycle 270 msec + IL Ver.pure 230 msec +``` + + The following command performs metadata validation checks and MSIL type safety verification checks for methods implemented in the assembly `myAssembly.exe`. Peverify.exe stops, however, when it reaches the maximum error count of 100. The tool also ignores the specified error codes. + +```console +peverify myAssembly.exe /break=100 /ignore=0x12345678,0xABCD1234 +``` + + The following command produces the same result as the above previous example, but specifies the error codes to ignore in the response file `ignoreErrors.rsp`. + +```console +peverify myAssembly.exe /break=100 /ignore@ignoreErrors.rsp +``` + + The response file can contain a comma-separated list of error codes. + ```text -0x12345678, 0xABCD1234 -``` - - Alternatively, the response file can be formatted with one error code per line. - +0x12345678, 0xABCD1234 +``` + + Alternatively, the response file can be formatted with one error code per line. + ```text -0x12345678 -0xABCD1234 -``` - +0x12345678 +0xABCD1234 +``` + ## See also - [Tools](index.md) diff --git a/docs/framework/tools/sos-dll-sos-debugging-extension.md b/docs/framework/tools/sos-dll-sos-debugging-extension.md index 8662e61ad23c7..71fc3b9ba7de3 100644 --- a/docs/framework/tools/sos-dll-sos-debugging-extension.md +++ b/docs/framework/tools/sos-dll-sos-debugging-extension.md @@ -35,7 +35,7 @@ The SOS debugging extension (SOS.dll) helps you debug managed programs in Visual |**DumpClass** \<*EEClass address*>|Displays information about the `EEClass` structure associated with a type.

The **DumpClass** command displays static field values but does not display nonstatic field values.

Use the **DumpMT**, **DumpObj**, **Name2EE**, or **Token2EE** command to get an `EEClass` structure address.| |**DumpDomain** [\<*domain address*>]|Enumerates each object that is loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process.| |**DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]]|Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes (hex).

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes (hex).

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address.| -|**DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*>|Displays the Microsoft intermediate language (MSIL) that is associated with a managed method.

Note that dynamic MSIL is emitted differently than MSIL that is loaded from an assembly. Dynamic MSIL refers to objects in a managed object array rather than to metadata tokens.| +|**DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*>|Displays the common intermediate language (CIL) that is associated with a managed method.

Note that dynamic CIL is emitted differently than CIL that is loaded from an assembly. Dynamic CIL refers to objects in a managed object array rather than to metadata tokens.| |**DumpLog** [**-addr** \<*addressOfStressLog*>] [<*Filenam*`e`>]|Writes the contents of an in-memory stress log to the specified file. If you do not specify a name, this command creates a file called StressLog.txt in the current directory.

The in-memory stress log helps you diagnose stress failures without using locks or I/O. To enable the stress log, set the following registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\.NETFramework:

(DWORD) StressLog = 1

(DWORD) LogFacility = 0xffffffff

(DWORD) StressLogSize = 65536

The optional `-addr` option lets you specify a stress log other than the default log.| |**DumpMD** \<*MethodDesc address*>|Displays information about a `MethodDesc` structure at the specified address.

You can use the **IP2MD** command to get the `MethodDesc` structure address from a managed function.| |**DumpMT** [**-MD**] \<*MethodTable address*>|Displays information about a method table at the specified address. Specifying the **-MD** option displays a list of all methods defined with the object.

Each managed object contains a method table pointer.| diff --git a/docs/framework/ui-automation/implementing-the-ui-automation-value-control-pattern.md b/docs/framework/ui-automation/implementing-the-ui-automation-value-control-pattern.md index 2f02581a1e11b..a1c6a30aedd0c 100644 --- a/docs/framework/ui-automation/implementing-the-ui-automation-value-control-pattern.md +++ b/docs/framework/ui-automation/implementing-the-ui-automation-value-control-pattern.md @@ -6,7 +6,6 @@ helpviewer_keywords: - "control patterns, Value" - "UI Automation, Value control pattern" - "Value control pattern" -ms.assetid: b0fcdd87-3add-4345-bca9-e891205e02ba --- # Implementing the UI Automation Value Control Pattern @@ -70,6 +69,6 @@ Example of Color Swatch String Mapping - [UI Automation Control Patterns Overview](ui-automation-control-patterns-overview.md) - [Support Control Patterns in a UI Automation Provider](support-control-patterns-in-a-ui-automation-provider.md) - [UI Automation Control Patterns for Clients](ui-automation-control-patterns-for-clients.md) -- [ValuePattern Insert Text Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/InsertText) +- [ValuePattern Insert Text Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/InsertText) - [UI Automation Tree Overview](ui-automation-tree-overview.md) - [Use Caching in UI Automation](use-caching-in-ui-automation.md) diff --git a/docs/framework/ui-automation/index.md b/docs/framework/ui-automation/index.md index 8ce046af18927..58e3713747ba9 100644 --- a/docs/framework/ui-automation/index.md +++ b/docs/framework/ui-automation/index.md @@ -2,11 +2,10 @@ title: "Microsoft UI Automation" description: See articles about Microsoft UI Automation, an accessibility framework for Microsoft Windows. This documentation describes UI Automation API for managed code. ms.date: "03/30/2017" -f1_keywords: +f1_keywords: - "AutoGeneratedOrientationPage" -helpviewer_keywords: +helpviewer_keywords: - "UI Automation" -ms.assetid: e7ec856e-41ee-47b1-9d57-b75a3dad088c --- # Microsoft UI Automation @@ -29,4 +28,4 @@ ms.assetid: e7ec856e-41ee-47b1-9d57-b75a3dad088c ## Related sections -- [Accessibility Samples](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility) +- [Accessibility Samples](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility) diff --git a/docs/framework/ui-automation/invoke-a-control-using-ui-automation.md b/docs/framework/ui-automation/invoke-a-control-using-ui-automation.md index b581c51dafc4d..b327191942c50 100644 --- a/docs/framework/ui-automation/invoke-a-control-using-ui-automation.md +++ b/docs/framework/ui-automation/invoke-a-control-using-ui-automation.md @@ -37,4 +37,4 @@ ms.topic: how-to ## See also -- [InvokePattern, ExpandCollapsePattern, and TogglePattern Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/InvokePattern) +- [InvokePattern, ExpandCollapsePattern, and TogglePattern Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/InvokePattern) diff --git a/docs/framework/ui-automation/move-a-ui-automation-element.md b/docs/framework/ui-automation/move-a-ui-automation-element.md index 2fcdea6a319e4..2632195734f15 100644 --- a/docs/framework/ui-automation/move-a-ui-automation-element.md +++ b/docs/framework/ui-automation/move-a-ui-automation-element.md @@ -29,4 +29,4 @@ ms.topic: how-to ## See also -- [WindowPattern Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/WindowMove) +- [WindowPattern Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/WindowMove) diff --git a/docs/framework/ui-automation/textpattern-and-embedded-objects-overview.md b/docs/framework/ui-automation/textpattern-and-embedded-objects-overview.md index 00f2d1d0d3b98..4da53bed72d03 100644 --- a/docs/framework/ui-automation/textpattern-and-embedded-objects-overview.md +++ b/docs/framework/ui-automation/textpattern-and-embedded-objects-overview.md @@ -7,7 +7,6 @@ helpviewer_keywords: - "embedded objects, accessing" - "accessing embedded objects" - "embedded objects, UI Automation" -ms.assetid: 93fdfbb9-0025-4b72-8ca0-0714adbb70d5 --- # TextPattern and Embedded Objects Overview @@ -162,4 +161,4 @@ Examples of how a text range is adjusted for Move() and ExpandToEnclosingUnit() - [Access Embedded Objects Using UI Automation](access-embedded-objects-using-ui-automation.md) - [Expose the Content of a Table Using UI Automation](expose-the-content-of-a-table-using-ui-automation.md) - [Traverse Text Using UI Automation](traverse-text-using-ui-automation.md) -- [TextPattern Search and Selection Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/FindText) +- [TextPattern Search and Selection Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/FindText) diff --git a/docs/framework/ui-automation/ui-automation-and-screen-scaling.md b/docs/framework/ui-automation/ui-automation-and-screen-scaling.md index 680b8861c4405..82d0a1c8eb244 100644 --- a/docs/framework/ui-automation/ui-automation-and-screen-scaling.md +++ b/docs/framework/ui-automation/ui-automation-and-screen-scaling.md @@ -10,7 +10,6 @@ helpviewer_keywords: - "screens, scaling" - "UI (user interface), automation" - "UI Automation" -ms.assetid: 4380cad7-e509-448f-b9a5-6de042605fd4 --- # UI Automation and Screen Scaling @@ -63,7 +62,7 @@ Starting with Windows Vista, Windows enables users to change the dots per inch ( [!code-csharp[Highlighter#101](../../../samples/snippets/csharp/VS_Snippets_Wpf/Highlighter/CSharp/NativeMethods.cs#101)] [!code-vb[Highlighter#101](../../../samples/snippets/visualbasic/VS_Snippets_Wpf/Highlighter/VisualBasic/NativeMethods.vb#101)] - This function makes the entire process dpi-aware, meaning that all windows that belong to the process are unscaled. In the [Highlighter Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/Highlighter), for instance, the four windows that make up the highlight rectangle are located at the physical coordinates obtained from UI Automation, not the logical coordinates. If the sample were not dpi-aware, the highlight would be drawn at the logical coordinates on the desktop, which would result in incorrect placement in a non-96- dpi environment. + This function makes the entire process dpi-aware, meaning that all windows that belong to the process are unscaled. In the [Highlighter Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/Highlighter), for instance, the four windows that make up the highlight rectangle are located at the physical coordinates obtained from UI Automation, not the logical coordinates. If the sample were not dpi-aware, the highlight would be drawn at the logical coordinates on the desktop, which would result in incorrect placement in a non-96- dpi environment. 2. To get cursor coordinates, call the Win32 function `GetPhysicalCursorPos`. The following example shows how to declare and use this function. @@ -77,4 +76,4 @@ Starting with Windows Vista, Windows enables users to change the dots per inch ( ## See also -- [Highlighter Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/Highlighter) +- [Highlighter Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/Highlighter) diff --git a/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md b/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md index b671830d8245e..98c94ef53dbdb 100644 --- a/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md +++ b/docs/framework/ui-automation/ui-automation-control-patterns-for-clients.md @@ -5,7 +5,6 @@ ms.date: "03/30/2017" helpviewer_keywords: - "UI Automation, control patterns for clients" - "control patterns, UI Automation clients" -ms.assetid: 571561d8-5f49-43a9-a054-87735194e013 --- # UI Automation Control Patterns for Clients @@ -53,6 +52,6 @@ ms.assetid: 571561d8-5f49-43a9-a054-87735194e013 - [Invoke a Control Using UI Automation](invoke-a-control-using-ui-automation.md) - [Get the Toggle State of a Check Box Using UI Automation](get-the-toggle-state-of-a-check-box-using-ui-automation.md) - [Control Pattern Mapping for UI Automation Clients](control-pattern-mapping-for-ui-automation-clients.md) -- [TextPattern Insert Text Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/InsertText) -- [TextPattern Search and Selection Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/FindText) -- [InvokePattern, ExpandCollapsePattern, and TogglePattern Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/InvokePattern) +- [TextPattern Insert Text Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/InsertText) +- [TextPattern Search and Selection Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/FindText) +- [InvokePattern, ExpandCollapsePattern, and TogglePattern Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/InvokePattern) diff --git a/docs/framework/ui-automation/ui-automation-events-for-clients.md b/docs/framework/ui-automation/ui-automation-events-for-clients.md index 4272a2d79afc7..8ed5c6b08657f 100644 --- a/docs/framework/ui-automation/ui-automation-events-for-clients.md +++ b/docs/framework/ui-automation/ui-automation-events-for-clients.md @@ -5,7 +5,6 @@ ms.date: "03/30/2017" helpviewer_keywords: - "UI Automation, events for clients" - "events, UI Automation clients" -ms.assetid: b909e388-3f24-4997-b6d4-bd9c35c2dc27 --- # UI Automation Events for Clients @@ -60,4 +59,4 @@ ms.assetid: b909e388-3f24-4997-b6d4-bd9c35c2dc27 - [Subscribe to UI Automation Events](subscribe-to-ui-automation-events.md) - [UI Automation Events Overview](ui-automation-events-overview.md) - [UI Automation Properties Overview](ui-automation-properties-overview.md) -- [TrackFocus Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/FocusTracker) +- [TrackFocus Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/FocusTracker) diff --git a/docs/framework/ui-automation/ui-automation-textpattern-overview.md b/docs/framework/ui-automation/ui-automation-textpattern-overview.md index d6e8109aa6d2e..0dfa31e3b9946 100644 --- a/docs/framework/ui-automation/ui-automation-textpattern-overview.md +++ b/docs/framework/ui-automation/ui-automation-textpattern-overview.md @@ -6,7 +6,6 @@ helpviewer_keywords: - "UI Automation, TextPattern class" - "TextPattern class" - "classes, TextPattern" -ms.assetid: 41787927-df1f-4f4a-aba3-641662854fc4 --- # UI Automation TextPattern Overview @@ -19,7 +18,7 @@ This overview describes how to use Microsoft UI Automation to expose the textual Exposing the textual content of a control is accomplished through the use of the control pattern, which represents the contents of a text container as a text stream. In turn, requires the support of the class to expose format and style attributes. supports by representing contiguous or multiple, disjoint text spans in a text container with a collection of and endpoints. supports functionality such as selection, comparison, retrieval and traversal. > [!NOTE] -> The classes do not provide a means to insert or modify text. However, depending on the control, this may be accomplished by the UI Automation or through direct keyboard input. See the [TextPattern Insert Text Sample](https://github.com/Microsoft/WPF-Samples/tree/master/Accessibility/InsertText) for an example. +> The classes do not provide a means to insert or modify text. However, depending on the control, this may be accomplished by the UI Automation or through direct keyboard input. See the [TextPattern Insert Text Sample](https://github.com/Microsoft/WPF-Samples/tree/main/Accessibility/InsertText) for an example. The functionality described in this overview is vital to assistive technology vendors and their end users. Assistive technologies can use UI Automation to gather complete text formatting information for the user and provide programmatic navigation and selection of text by (character, word, line, or paragraph). diff --git a/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md b/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md index 8f60c7be358d4..957214acc91fe 100644 --- a/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md +++ b/docs/framework/unmanaged-api/constants-unmanaged-api-reference.md @@ -2,7 +2,7 @@ description: "Learn more about: Constants (Unmanaged API Reference)" title: "Constants (Unmanaged API Reference)" ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "constants for unmanaged API [.NET Framework]" - "native API reference [.NET Framework], constants" - "unmanaged API reference [.NET Framework], constants" @@ -10,43 +10,43 @@ ms.assetid: 77526f65-b71c-4483-9d19-3a3751fd8a45 --- # Constants (Unmanaged API Reference) -This topic describes the language type, language vendor, and document type constants that are defined in CorSym.idl. - -## Language Type Constants - - The following table shows language type constants, which represent GUIDs that identify programming languages. - -|Symbol|Description| -|------------|-----------------| -|CorSym_LanguageType_C|Indicates the C language.| -|CorSym_LanguageType_CPlusPlus|Indicates the C++ language.| -|CorSym_LanguageType_CSharp|Indicates the C# language.| -|CorSym_LanguageType_Basic|Indicates the Basic language.| -|CorSym_LanguageType_Java|Indicates the Java language.| -|CorSym_LanguageType_Cobol|Indicates the COBOL language.| -|CorSym_LanguageType_Pascal|Indicates the Pascal language.| -|CorSym_LanguageType_ILAssembly|Indicates the Microsoft intermediate language (MSIL) assembly code.| -|CorSym_LanguageType_JScript|Indicates the JScript language.| -|CorSym_LanguageType_SMC|Indicates the SMC language.| -|CorSym_LanguageType_MCPlusPlus|Indicates the C++ language enabled for the .NET Framework.| - -## Language Vendor Constants - - The following table shows language vendor constants, which represent GUIDs that identify programming language vendors. - -|Symbol|Description| -|------------|-----------------| -|CorSym_LanguageVendor_Microsoft|Indicates Microsoft.| - -## Document Type Constants - - The following table shows document type constants, which represent GUIDs that identify document types. - -|Symbol|Description| -|------------|-----------------| -|CorSym_DocumentType_Text|Indicates a text document.| -|CorSym_DocumentType_MC|Indicates a non-text document.| - +This topic describes the language type, language vendor, and document type constants that are defined in CorSym.idl. + +## Language Type Constants + + The following table shows language type constants, which represent GUIDs that identify programming languages. + +|Symbol|Description| +|------------|-----------------| +|CorSym_LanguageType_C|Indicates the C language.| +|CorSym_LanguageType_CPlusPlus|Indicates the C++ language.| +|CorSym_LanguageType_CSharp|Indicates the C# language.| +|CorSym_LanguageType_Basic|Indicates the Basic language.| +|CorSym_LanguageType_Java|Indicates the Java language.| +|CorSym_LanguageType_Cobol|Indicates the COBOL language.| +|CorSym_LanguageType_Pascal|Indicates the Pascal language.| +|CorSym_LanguageType_ILAssembly|Indicates the common intermediate language (CIL) assembly code.| +|CorSym_LanguageType_JScript|Indicates the JScript language.| +|CorSym_LanguageType_SMC|Indicates the SMC language.| +|CorSym_LanguageType_MCPlusPlus|Indicates the C++ language enabled for the .NET Framework.| + +## Language Vendor Constants + + The following table shows language vendor constants, which represent GUIDs that identify programming language vendors. + +|Symbol|Description| +|------------|-----------------| +|CorSym_LanguageVendor_Microsoft|Indicates Microsoft.| + +## Document Type Constants + + The following table shows document type constants, which represent GUIDs that identify document types. + +|Symbol|Description| +|------------|-----------------| +|CorSym_DocumentType_Text|Indicates a text document.| +|CorSym_DocumentType_MC|Indicates a non-text document.| + ## See also - [Unmanaged API Reference](index.md) diff --git a/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md b/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md index fe17b8272d93a..e73ae5abc9787 100644 --- a/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-active-function-structure.md @@ -2,56 +2,56 @@ description: "Learn more about: COR_ACTIVE_FUNCTION Structure" title: "COR_ACTIVE_FUNCTION Structure" ms.date: "03/30/2017" -api_name: +api_name: - "COR_ACTIVE_FUNCTION" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "COR_ACTIVE_FUNCTION" -helpviewer_keywords: +helpviewer_keywords: - "COR_ACTIVE_FUNCTION structure [.NET Framework debugging]" ms.assetid: ed86185f-2152-459c-961f-10c06d62e83f -topic_type: +topic_type: - "apiref" --- # COR_ACTIVE_FUNCTION Structure -Contains information about the functions that are currently active in a thread's frames. This structure is used by the [ICorDebugThread2::GetActiveFunctions](icordebugthread2-getactivefunctions-method.md) method. - -## Syntax - -```cpp -typedef struct _COR_ACTIVE_FUNCTION { - ICorDebugAppDomain *pAppDomain; - ICorDebugModule *pModule; - ICorDebugFunction2 *pFunction; - ULONG32 ilOffset; - ULONG32 flags; -} COR_ACTIVE_FUNCTION; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`pAppDomain`|Pointer to the application domain owner of the `ilOffset` field.| -|`pModule`|Pointer to the module owner of the `ilOffset` field.| -|`pFunction`|Pointer to the function owner of the `ilOffset` field.| -|`ilOffset`|The Microsoft intermediate language (MSIL) offset of the frame.| -|`flags`|Reserved for future extensibility.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Contains information about the functions that are currently active in a thread's frames. This structure is used by the [ICorDebugThread2::GetActiveFunctions](icordebugthread2-getactivefunctions-method.md) method. + +## Syntax + +```cpp +typedef struct _COR_ACTIVE_FUNCTION { + ICorDebugAppDomain *pAppDomain; + ICorDebugModule *pModule; + ICorDebugFunction2 *pFunction; + ULONG32 ilOffset; + ULONG32 flags; +} COR_ACTIVE_FUNCTION; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`pAppDomain`|Pointer to the application domain owner of the `ilOffset` field.| +|`pModule`|Pointer to the module owner of the `ilOffset` field.| +|`pFunction`|Pointer to the function owner of the `ilOffset` field.| +|`ilOffset`|The common intermediate language (CIL) offset of the frame.| +|`flags`|Reserved for future extensibility.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Debugging Structures](debugging-structures.md) diff --git a/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md b/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md index f57099ce88a60..df8e4fb1ec58a 100644 --- a/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-debug-il-to-native-map-structure.md @@ -2,52 +2,52 @@ description: "Learn more about: COR_DEBUG_IL_TO_NATIVE_MAP Structure" title: "COR_DEBUG_IL_TO_NATIVE_MAP Structure" ms.date: "03/30/2017" -api_name: +api_name: - "COR_DEBUG_IL_TO_NATIVE_MAP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "COR_DEBUG_IL_TO_NATIVE_MAP" -helpviewer_keywords: +helpviewer_keywords: - "COR_DEBUG_IL_TO_NATIVE_MAP structure [.NET Framework debugging]" ms.assetid: 06f3b504-085f-4142-934a-25381fe23d4c -topic_type: +topic_type: - "apiref" --- # COR_DEBUG_IL_TO_NATIVE_MAP Structure -Contains the offsets that are used to map Microsoft intermediate language (MSIL) code to native code. - -## Syntax - -```cpp -typedef struct COR_DEBUG_IL_TO_NATIVE_MAP { - ULONG32 ilOffset; - ULONG32 nativeStartOffset; - ULONG32 nativeEndOffset; -} COR_DEBUG_IL_TO_NATIVE_MAP; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`ilOffset`|The offset of the MSIL code.| -|`nativeStartOffset`|The offset of the start of the native code.| -|`nativeEndOffset`|The offset of the end of the native code.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorDebug.idl - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Contains the offsets that are used to map common intermediate language (CIL) code to native code. + +## Syntax + +```cpp +typedef struct COR_DEBUG_IL_TO_NATIVE_MAP { + ULONG32 ilOffset; + ULONG32 nativeStartOffset; + ULONG32 nativeEndOffset; +} COR_DEBUG_IL_TO_NATIVE_MAP; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`ilOffset`|The offset of the CIL code.| +|`nativeStartOffset`|The offset of the start of the native code.| +|`nativeEndOffset`|The offset of the end of the native code.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorDebug.idl + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [GetILToNativeMapping Method](../profiling/icorprofilerinfo-getiltonativemapping-method.md) diff --git a/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md b/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md index 4b5c83666ea5e..6090f9f6223e1 100644 --- a/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md +++ b/docs/framework/unmanaged-api/debugging/cor-il-map-structure.md @@ -2,90 +2,90 @@ description: "Learn more about: COR_IL_MAP Structure" title: "COR_IL_MAP Structure" ms.date: "03/30/2017" -api_name: +api_name: - "COR_IL_MAP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "COR_IL_MAP" -helpviewer_keywords: +helpviewer_keywords: - "COR_IL_MAP structure [.NET Framework debugging]" ms.assetid: 534ebc17-963d-4b26-8375-8cd940281db3 -topic_type: +topic_type: - "apiref" --- # COR_IL_MAP Structure -Specifies changes in the relative offset of a function. - -## Syntax - -```cpp -typedef struct _COR_IL_MAP { +Specifies changes in the relative offset of a function. + +## Syntax + +```cpp +typedef struct _COR_IL_MAP { ULONG32 oldOffset; ULONG32 newOffset; - BOOL fAccurate; -} COR_IL_MAP; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`oldOffset`|The old Microsoft intermediate language (MSIL) offset relative to the beginning of the function.| -|`newOffset`|The new MSIL offset relative to the beginning of the function.| -|`fAccurate`|`true` if the mapping is known to be accurate; otherwise, `false`.| - -## Remarks - - The format of the map is as follows: The debugger will assume that `oldOffset` refers to an MSIL offset within the original, unmodified MSIL code. The `newOffset` parameter refers to the corresponding MSIL offset within the new, instrumented code. - - For stepping to work properly, the following requirements should be met: - -- The map should be sorted in ascending order. - -- Instrumented MSIL code should not be reordered. - -- Original MSIL code should not be removed. - -- The map should include entries to map all the sequence points from the program database (PDB) file. - - The map does not interpolate missing entries. The following example shows a map and its results. - - Map: - -- 0 old offset, 0 new offset - -- 5 old offset, 10 new offset - -- 9 old offset, 20 new offset - - Results: - -- An old offset of 0, 1, 2, 3, or 4 will be mapped to a new offset of 0. - -- An old offset of 5, 6, 7, or 8 will be mapped to new offset 10. - -- An old offset of 9 or higher will be mapped to new offset 20. - -- A new offset of 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9 will be mapped to old offset 0. - -- A new offset of 10, 11, 12, 13, 14, 15, 16, 17, 18, or 19 will be mapped to old offset 5. - -- A new offset of 20 or higher will be mapped to old offset 9. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorProf.idl - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - + BOOL fAccurate; +} COR_IL_MAP; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`oldOffset`|The old common intermediate language (CIL) offset relative to the beginning of the function.| +|`newOffset`|The new CIL offset relative to the beginning of the function.| +|`fAccurate`|`true` if the mapping is known to be accurate; otherwise, `false`.| + +## Remarks + + The format of the map is as follows: The debugger will assume that `oldOffset` refers to an CIL offset within the original, unmodified CIL code. The `newOffset` parameter refers to the corresponding CIL offset within the new, instrumented code. + + For stepping to work properly, the following requirements should be met: + +- The map should be sorted in ascending order. + +- Instrumented CIL code should not be reordered. + +- Original CIL code should not be removed. + +- The map should include entries to map all the sequence points from the program database (PDB) file. + + The map does not interpolate missing entries. The following example shows a map and its results. + + Map: + +- 0 old offset, 0 new offset + +- 5 old offset, 10 new offset + +- 9 old offset, 20 new offset + + Results: + +- An old offset of 0, 1, 2, 3, or 4 will be mapped to a new offset of 0. + +- An old offset of 5, 6, 7, or 8 will be mapped to new offset 10. + +- An old offset of 9 or higher will be mapped to new offset 20. + +- A new offset of 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9 will be mapped to old offset 0. + +- A new offset of 10, 11, 12, 13, 14, 15, 16, 17, 18, or 19 will be mapped to old offset 5. + +- A new offset of 20 or higher will be mapped to old offset 9. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorProf.idl + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Structures](debugging-structures.md) diff --git a/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md b/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md index 2cd4d5c77caeb..728cbebcbfb56 100644 --- a/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md +++ b/docs/framework/unmanaged-api/debugging/cordebugmappingresult-enumeration.md @@ -2,62 +2,62 @@ description: "Learn more about: CorDebugMappingResult Enumeration" title: "CorDebugMappingResult Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "CorDebugMappingResult" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "CorDebugMappingResult" -helpviewer_keywords: +helpviewer_keywords: - "CorDebugMappingResult enumeration [.NET Framework debugging]" ms.assetid: 701281dd-2936-45c8-a1f0-3bf7332b093b -topic_type: +topic_type: - "apiref" --- # CorDebugMappingResult Enumeration -Provides the details of how the value of the instruction pointer (IP) was obtained. - -## Syntax - -```cpp -typedef enum CorDebugMappingResult { - MAPPING_PROLOG = 0x1, - MAPPING_EPILOG = 0x2, - MAPPING_NO_INFO = 0x4, - MAPPING_UNMAPPED_ADDRESS = 0x8, - MAPPING_EXACT = 0x10, - MAPPING_APPROXIMATE = 0x20, -} CorDebugMappingResult; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`MAPPING_PROLOG`|The native code is in the prolog, so the value of the IP is 0.| -|`MAPPING_EPILOG`|The native code is in an epilog, so the value of the IP is the address of the last instruction of the method.| -|`MAPPING_NO_INFO`|No mapping information is available for the method, so the value of the IP is 0.| -|`MAPPING_UNMAPPED_ADDRESS`|Although there is mapping information for the method, the current address cannot be mapped to Microsoft intermediate language (MSIL) code. The value of the IP is 0.| -|`MAPPING_EXACT`|Either the method maps exactly to MSIL code or the frame has been interpreted, so the value of the IP is accurate.| -|`MAPPING_APPROXIMATE`|The method was successfully mapped, but the value of the IP may be approximate.| - -## Remarks - - You can use the [ICorDebugILFrame::GetIP](icordebugilframe-getip-method.md) method to obtain the value of the instruction pointer. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Provides the details of how the value of the instruction pointer (IP) was obtained. + +## Syntax + +```cpp +typedef enum CorDebugMappingResult { + MAPPING_PROLOG = 0x1, + MAPPING_EPILOG = 0x2, + MAPPING_NO_INFO = 0x4, + MAPPING_UNMAPPED_ADDRESS = 0x8, + MAPPING_EXACT = 0x10, + MAPPING_APPROXIMATE = 0x20, +} CorDebugMappingResult; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`MAPPING_PROLOG`|The native code is in the prolog, so the value of the IP is 0.| +|`MAPPING_EPILOG`|The native code is in an epilog, so the value of the IP is the address of the last instruction of the method.| +|`MAPPING_NO_INFO`|No mapping information is available for the method, so the value of the IP is 0.| +|`MAPPING_UNMAPPED_ADDRESS`|Although there is mapping information for the method, the current address cannot be mapped to common intermediate language (CIL) code. The value of the IP is 0.| +|`MAPPING_EXACT`|Either the method maps exactly to CIL code or the frame has been interpreted, so the value of the IP is accurate.| +|`MAPPING_APPROXIMATE`|The method was successfully mapped, but the value of the IP may be approximate.| + +## Remarks + + You can use the [ICorDebugILFrame::GetIP](icordebugilframe-getip-method.md) method to obtain the value of the instruction pointer. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Enumerations](debugging-enumerations.md) diff --git a/docs/framework/unmanaged-api/debugging/debugging-interfaces.md b/docs/framework/unmanaged-api/debugging/debugging-interfaces.md index f14467603f1cd..5109173db3228 100644 --- a/docs/framework/unmanaged-api/debugging/debugging-interfaces.md +++ b/docs/framework/unmanaged-api/debugging/debugging-interfaces.md @@ -2,7 +2,7 @@ description: "Learn more about: Debugging Interfaces" title: "Debugging Interfaces" ms.date: "02/07/2019" -helpviewer_keywords: +helpviewer_keywords: - "unmanaged interfaces [.NET Framework], debugging" - "debugging interfaces [.NET Framework]" - "interfaces [.NET Framework debugging]" @@ -10,432 +10,432 @@ ms.assetid: b6297c26-7624-4431-8af4-14112d07bcd5 --- # Debugging Interfaces -This section describes the unmanaged interfaces that handle the debugging of a program that is executing in the common language runtime (CLR). - -## In This Section +This section describes the unmanaged interfaces that handle the debugging of a program that is executing in the common language runtime (CLR). + +## In This Section [ICLRDataEnumMemoryRegions Interface](iclrdataenummemoryregions-interface.md)\ - Provides a method to enumerate regions of memory that are specified by callers. - + Provides a method to enumerate regions of memory that are specified by callers. + [ICLRDataEnumMemoryRegionsCallback Interface](iclrdataenummemoryregionscallback-interface.md)\ - Provides a callback method for `EnumMemoryRegions` to report to the debugger, the result of an attempt to enumerate a specified region of memory. - + Provides a callback method for `EnumMemoryRegions` to report to the debugger, the result of an attempt to enumerate a specified region of memory. + [ICLRDataTarget Interface](iclrdatatarget-interface.md)\ - Provides methods for interaction with a target CLR process. - + Provides methods for interaction with a target CLR process. + [ICLRDataTarget2 Interface](iclrdatatarget2-interface.md)\ - A subclass of `ICLRDataTarget` that is used by the data access services layer to manipulate virtual memory regions in the target process. - + A subclass of `ICLRDataTarget` that is used by the data access services layer to manipulate virtual memory regions in the target process. + [ICLRDataTarget3 Interface](iclrdatatarget3-interface.md)\ - A subclass of [ICLRDataTarget2](iclrdatatarget2-interface.md) that provides access to exception information. - + A subclass of [ICLRDataTarget2](iclrdatatarget2-interface.md) that provides access to exception information. + [ICLRDebugging Interface](iclrdebugging-interface.md)\ - Provides methods that handle loading and unloading modules for debugging. - + Provides methods that handle loading and unloading modules for debugging. + [ICLRDebuggingLibraryProvider Interface](iclrdebugginglibraryprovider-interface.md)\ - Includes the [ProvideLibrary Method](iclrdebugginglibraryprovider-providelibrary-method.md) method, which gets a library provider callback interface that allows common language runtime version-specific debugging libraries to be located and loaded on demand. - + Includes the [ProvideLibrary Method](iclrdebugginglibraryprovider-providelibrary-method.md) method, which gets a library provider callback interface that allows common language runtime version-specific debugging libraries to be located and loaded on demand. + [ICLRMetadataLocator Interface](iclrmetadatalocator-interface.md)\ - Interface used by the data access services layer to locate metadata of assemblies in a target process. - + Interface used by the data access services layer to locate metadata of assemblies in a target process. + [ICorDebug Interface](icordebug-interface.md)\ - Provides methods that allow developers to debug applications in the CLR environment. - + Provides methods that allow developers to debug applications in the CLR environment. + [ICorDebugAppDomain Interface](icordebugappdomain-interface.md)\ - Provides methods for debugging application domains. - + Provides methods for debugging application domains. + [ICorDebugAppDomain2 Interface](icordebugappdomain2-interface.md)\ - Provides methods to work with arrays, pointers, function pointers, and ByRef types. This interface is an extension of the `ICorDebugAppDomain` interface. - + Provides methods to work with arrays, pointers, function pointers, and ByRef types. This interface is an extension of the `ICorDebugAppDomain` interface. + [ICorDebugAppDomain3 Interface](icordebugappdomain3-interface.md)\ - Provides methods to work with the Windows Runtime types in an application domain. This interface is an extension of the `ICorDebugAppDomain` and `ICorDebugAppDomain2` interfaces. - + Provides methods to work with the Windows Runtime types in an application domain. This interface is an extension of the `ICorDebugAppDomain` and `ICorDebugAppDomain2` interfaces. + [ICorDebugAppDomain4 Interface](icordebugappdomain4-interface.md)\ - Logically extends the [ICorDebugAppDomain](icordebugappdomain-interface.md) interface to get a managed object from a COM callable wrapper. - + Logically extends the [ICorDebugAppDomain](icordebugappdomain-interface.md) interface to get a managed object from a COM callable wrapper. + [ICorDebugAppDomainEnum Interface](icordebugappdomainenum-interface.md)\ - Provides a method that returns a specified number of `ICorDebugAppDomain` values starting at the next location in the enumeration. - + Provides a method that returns a specified number of `ICorDebugAppDomain` values starting at the next location in the enumeration. + [ICorDebugArrayValue Interface](icordebugarrayvalue-interface.md)\ - A subclass of `ICorDebugHeapValue` that represents a single-dimensional or multi-dimensional array. - + A subclass of `ICorDebugHeapValue` that represents a single-dimensional or multi-dimensional array. + [ICorDebugAssembly Interface](icordebugassembly-interface.md)\ - Represents an assembly. - + Represents an assembly. + [ICorDebugAssembly2 Interface](icordebugassembly2-interface.md)\ - Represents an assembly. This interface is an extension of the `ICorDebugAssembly` interface. - + Represents an assembly. This interface is an extension of the `ICorDebugAssembly` interface. + [ICorDebugAssembly3 Interface](icordebugassembly3-interface.md)\ - Logically extends the [ICorDebugAssembly](icordebugassembly-interface.md) interface to provide support for container assemblies and their contained assemblies. **Available on .NET Native only.** - + Logically extends the [ICorDebugAssembly](icordebugassembly-interface.md) interface to provide support for container assemblies and their contained assemblies. **Available on .NET Native only.** + [ICorDebugAssemblyEnum Interface](icordebugassemblyenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugAssembly` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugAssembly` arrays. + [ICorDebugBlockingObjectEnum Interface](icordebugblockingobjectenum-interface.md)\ - Provides an enumerator for a list of [CorDebugBlockingObject](cordebugblockingobject-structure.md) structures. - + Provides an enumerator for a list of [CorDebugBlockingObject](cordebugblockingobject-structure.md) structures. + [ICorDebugBoxValue Interface](icordebugboxvalue-interface.md)\ - A subclass of `ICorDebugHeapValue` that represents a boxed value class object. - + A subclass of `ICorDebugHeapValue` that represents a boxed value class object. + [ICorDebugBreakpoint Interface](icordebugbreakpoint-interface.md)\ - Represents a breakpoint in a function or a watch point on a value. - + Represents a breakpoint in a function or a watch point on a value. + [ICorDebugBreakpointEnum Interface](icordebugbreakpointenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugBreakpoint` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugBreakpoint` arrays. + [ICorDebugChain Interface](icordebugchain-interface.md)\ - Represents a segment of a physical or logical call stack. - + Represents a segment of a physical or logical call stack. + [ICorDebugChainEnum Interface](icordebugchainenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugChain` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugChain` arrays. + [ICorDebugClass Interface](icordebugclass-interface.md)\ - Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugClass` represents the uninstantiated generic type. - + Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugClass` represents the uninstantiated generic type. + [ICorDebugClass2 Interface](icordebugclass2-interface.md)\ - Represents a generic class or a class with a method parameter of type . This interface extends `ICorDebugClass`. - + Represents a generic class or a class with a method parameter of type . This interface extends `ICorDebugClass`. + [ICorDebugCode Interface](icordebugcode-interface1.md)\ - Represents a segment of either Microsoft intermediate language (MSIL) code or native code. - + Represents a segment of either common intermediate language (CIL) code or native code. + [ICorDebugCode2 Interface](icordebugcode2-interface.md)\ - Provides methods that extend the capabilities of `ICorDebugCode`. - + Provides methods that extend the capabilities of `ICorDebugCode`. + [ICorDebugCode3 Interface](icordebugcode3-interface.md)\ - Provides a method that extends [ICorDebugCode](icordebugcode-interface1.md) and [ICorDebugCode2](icordebugcode2-interface.md) to provide information about a managed return value. - + Provides a method that extends [ICorDebugCode](icordebugcode-interface1.md) and [ICorDebugCode2](icordebugcode2-interface.md) to provide information about a managed return value. + [ICorDebugCode4 Interface](icordebugcode4-interface.md)\ - Provides a method that enables a debugger to enumerate the local variables and arguments in a function. - + Provides a method that enables a debugger to enumerate the local variables and arguments in a function. + [ICorDebugCodeEnum Interface](icordebugcodeenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugCode` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugCode` arrays. + [ICorDebugComObjectValue Interface](icordebugcomobjectvalue-interface.md)\ - Provides methods to retrieve cached interface objects. - + Provides methods to retrieve cached interface objects. + [ICorDebugContext Interface](icordebugcontext-interface.md)\ - Represents a context object. This interface has not been implemented yet. - + Represents a context object. This interface has not been implemented yet. + [ICorDebugController Interface](icordebugcontroller-interface.md)\ - Represents a scope, either a or an , in which code execution context can be controlled. - + Represents a scope, either a or an , in which code execution context can be controlled. + [ICorDebugDataTarget Interface](icordebugdatatarget-interface.md)\ - Provides a callback interface that provides access to a particular target process. - + Provides a callback interface that provides access to a particular target process. + [ICorDebugDataTarget2 Interface](icordebugdatatarget2-interface.md)\ - Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface. **Available on .NET Native only.** - + Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface. **Available on .NET Native only.** + [ICorDebugDataTarget3 Interface](icordebugdatatarget3-interface.md)\ - Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to provide information about loaded modules. **Available on .NET Native only.** - + Logically extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to provide information about loaded modules. **Available on .NET Native only.** + [ICorDebugDebugEvent Interface](icordebugdebugevent-interface.md)\ - Defines the base interface from which all `ICorDebug` debug events derive. **Available on .NET Native only.** - + Defines the base interface from which all `ICorDebug` debug events derive. **Available on .NET Native only.** + [ICorDebugEditAndContinueErrorInfo Interface](icordebugeditandcontinueerrorinfo-interface.md)\ - Obsolete. Do not use this interface. - + Obsolete. Do not use this interface. + [ICorDebugEditAndContinueSnapshot Interface](icordebugeditandcontinuesnapshot-interface.md)\ - Obsolete. Do not use this interface. - + Obsolete. Do not use this interface. + [ICorDebugEnum Interface](icordebugenum-interface1.md)\ - Serves as the abstract base interface for debugging enumerators. - + Serves as the abstract base interface for debugging enumerators. + [ICorDebugErrorInfoEnum Interface](icordebugerrorinfoenum-interface.md)\ - Obsolete. Do not use this interface. - + Obsolete. Do not use this interface. + [ICorDebugEval Interface](icordebugeval-interface.md)\ - Provides methods to enable the debugger to execute code within the context of the code being debugged. - + Provides methods to enable the debugger to execute code within the context of the code being debugged. + [ICorDebugEval2 Interface](icordebugeval2-interface.md)\ - Extends `ICorDebugEval` to provide support for generic types. - + Extends `ICorDebugEval` to provide support for generic types. + [ICorDebugExceptionDebugEvent Interface](icordebugexceptiondebugevent-interface.md)\ - Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support exception events. **Available on .NET Native only.** - + Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support exception events. **Available on .NET Native only.** + [ICorDebugExceptionObjectCallStackEnum Interface](icordebugexceptionobjectcallstackenum-interface.md)\ - Provides an enumerator for call stack information that is embedded in an exception object. - + Provides an enumerator for call stack information that is embedded in an exception object. + [ICorDebugExceptionObjectValue Interface](icordebugexceptionobjectvalue-interface.md)\ - Extends the [ICorDebugObjectValue](icordebugobjectvalue-interface.md) interface to provide stack trace information from a managed exception object. - + Extends the [ICorDebugObjectValue](icordebugobjectvalue-interface.md) interface to provide stack trace information from a managed exception object. + [ICorDebugFrame Interface](icordebugframe-interface.md)\ - Represents a frame on the current stack. - + Represents a frame on the current stack. + [ICorDebugFrameEnum Interface](icordebugframeenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugFrame` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugFrame` arrays. + [ICorDebugFunction Interface](icordebugfunction-interface1.md)\ - Represents a managed function or method. - + Represents a managed function or method. + [ICorDebugFunction2 Interface](icordebugfunction2-interface.md)\ - Logically extends `ICorDebugFunction` to provide support for Just My Code step-through debugging. - + Logically extends `ICorDebugFunction` to provide support for Just My Code step-through debugging. + [ICorDebugFunction3 Interface](icordebugfunction3-interface.md)\ - Logically extends the [ICorDebugFunction](icordebugfunction-interface1.md) interface to provide access to code from a ReJIT request. - + Logically extends the [ICorDebugFunction](icordebugfunction-interface1.md) interface to provide access to code from a ReJIT request. + [ICorDebugFunctionBreakpoint Interface](icordebugfunctionbreakpoint-interface.md)\ - Extends `ICorDebugBreakpoint` to support breakpoints within functions. - + Extends `ICorDebugBreakpoint` to support breakpoints within functions. + [ICorDebugGCReferenceEnum Interface](icordebuggcreferenceenum-interface.md)\ - Provides an enumerator for objects that will be garbage-collected. - + Provides an enumerator for objects that will be garbage-collected. + [ICorDebugGenericValue Interface](icordebuggenericvalue-interface.md)\ - A subclass of `ICorDebugValue` that applies to all values. This interface provides Get and Set methods for the value. - + A subclass of `ICorDebugValue` that applies to all values. This interface provides Get and Set methods for the value. + [ICorDebugGuidToTypeEnum Interface](icordebugguidtotypeenum-interface.md)\ - Provides an enumerator for an object that maps GUIDs and their corresponding `ICorDebugType` objects. - + Provides an enumerator for an object that maps GUIDs and their corresponding `ICorDebugType` objects. + [ICorDebugHandleValue Interface](icordebughandlevalue-interface.md)\ - A subclass of `ICorDebugReferenceValue` that represents a reference value to which the debugger has created a handle for garbage collection. - + A subclass of `ICorDebugReferenceValue` that represents a reference value to which the debugger has created a handle for garbage collection. + [ICorDebugHeapEnum Interface](icordebugheapenum-interface.md)\ - Provides an enumerator for objects on the managed heap. - + Provides an enumerator for objects on the managed heap. + [ICorDebugHeapSegmentEnum Interface](icordebugheapsegmentenum-interface.md)\ - Provides an enumerator for the memory regions of the managed heap. - + Provides an enumerator for the memory regions of the managed heap. + [ICorDebugHeapValue Interface](icordebugheapvalue-interface.md)\ - A subclass of `ICorDebugValue` that represents an object that has been collected by the CLR garbage collector. - + A subclass of `ICorDebugValue` that represents an object that has been collected by the CLR garbage collector. + [ICorDebugHeapValue2 Interface](icordebugheapvalue2-interface1.md)\ - An extension of `ICorDebugHeapValue` that provides support for runtime handles. - + An extension of `ICorDebugHeapValue` that provides support for runtime handles. + [ICorDebugHeapValue3 Interface](icordebugheapvalue3-interface.md)\ - Exposes the monitor lock properties of objects. - + Exposes the monitor lock properties of objects. + [ICorDebugILCode Interface](icordebugilcode-interface.md)\ - Represents a segment of intermediate language (IL) code. - + Represents a segment of intermediate language (IL) code. + [ICorDebugILCode2 Interface](icordebugilcode2-interface.md)\ - Logically extends the [ICorDebugILCode](icordebugilcode-interface.md) interface to provide methods that return the token for a function's local variable signature, and that map a profiler's instrumented intermediate language (IL) offsets to original method IL offsets. - + Logically extends the [ICorDebugILCode](icordebugilcode-interface.md) interface to provide methods that return the token for a function's local variable signature, and that map a profiler's instrumented intermediate language (IL) offsets to original method IL offsets. + [ICorDebugILFrame Interface](icordebugilframe-interface.md)\ - Represents a stack frame of MSIL code. - + Represents a stack frame of CIL code. + [ICorDebugILFrame2 Interface](icordebugilframe2-interface.md)\ - A logical extension of `ICorDebugILFrame`. - + A logical extension of `ICorDebugILFrame`. + [ICorDebugILFrame3 Interface](icordebugilframe3-interface.md)\ - Provides a method that encapsulates the return value of a function. - + Provides a method that encapsulates the return value of a function. + [ICorDebugILFrame4 Interface](icordebugilframe4-interface.md)\ - Provides methods that allow you to access the local variables and code in a stack frame of intermediate language (IL) code. A parameter specifies whether the debugger has access to variables and code added in profiler ReJIT instrumentation. - + Provides methods that allow you to access the local variables and code in a stack frame of intermediate language (IL) code. A parameter specifies whether the debugger has access to variables and code added in profiler ReJIT instrumentation. + [ICorDebugInstanceFieldSymbol Interface](icordebuginstancefieldsymbol-interface.md)\ - Represents the debug symbol information for an instance field. **Available on .NET Native only.** - + Represents the debug symbol information for an instance field. **Available on .NET Native only.** + [ICorDebugInternalFrame Interface](icordebuginternalframe-interface.md)\ - Identifies frame types for the debugger. - + Identifies frame types for the debugger. + [ICorDebugInternalFrame2 Interface](icordebuginternalframe2-interface.md)\ - Provides information about internal frames, including stack address and position in relation to [ICorDebugFrame](icordebugframe-interface.md) objects. - + Provides information about internal frames, including stack address and position in relation to [ICorDebugFrame](icordebugframe-interface.md) objects. + [ICorDebugLoadedModule Interface](icordebugloadedmodule-interface.md)\ - Provides information about a loaded module. **Available on .NET Native only.** - + Provides information about a loaded module. **Available on .NET Native only.** + [ICorDebugManagedCallback Interface](icordebugmanagedcallback-interface.md)\ - Provides methods to process debugger callbacks. - + Provides methods to process debugger callbacks. + [ICorDebugManagedCallback2 Interface](icordebugmanagedcallback2-interface.md)\ - Provides methods to support debugger exception handling and managed debugging assistants (MDAs). `ICorDebugManagedCallback2` is a logical extension of `ICorDebugManagedCallback`. - + Provides methods to support debugger exception handling and managed debugging assistants (MDAs). `ICorDebugManagedCallback2` is a logical extension of `ICorDebugManagedCallback`. + [ICorDebugManagedCallback3 Interface](icordebugmanagedcallback3-interface.md)\ - Provides a callback method that indicates that an enabled custom debugger notification has been raised. - + Provides a callback method that indicates that an enabled custom debugger notification has been raised. + [ICorDebugMDA Interface](icordebugmda-interface.md)\ - Represents a managed debugging assistant (MDA) message. - + Represents a managed debugging assistant (MDA) message. + [ICorDebugMemoryBuffer Interface](icordebugmemorybuffer-interface.md)\ - Represents an in-memory buffer. **Available on .NET Native only.** - + Represents an in-memory buffer. **Available on .NET Native only.** + [ICorDebugMergedAssemblyRecord Interface](icordebugmergedassemblyrecord-interface.md)\ - Provides information about a merged assembly. **Available on .NET Native only.** - + Provides information about a merged assembly. **Available on .NET Native only.** + [ICorDebugMetaDataLocator Interface](icordebugmetadatalocator-interface.md)\ - Provides metadata information to the debugger. - + Provides metadata information to the debugger. + [ICorDebugModule Interface](icordebugmodule-interface.md)\ - Represents a CLR module, which is either an executable or a dynamic-link library (DLL). - + Represents a CLR module, which is either an executable or a dynamic-link library (DLL). + [ICorDebugModule2 Interface](icordebugmodule2-interface.md)\ - Serves as a logical extension to `ICorDebugModule`. - + Serves as a logical extension to `ICorDebugModule`. + [ICorDebugModule3 Interface](icordebugmodule3-interface.md)\ - Creates a symbol reader for a dynamic module. + Creates a symbol reader for a dynamic module. [ICorDebugModule4 Interface](icordebugmodule4-interface.md)\ - Provides a method that determines whether the module is loaded into memory in mapped/hydrated format. - + Provides a method that determines whether the module is loaded into memory in mapped/hydrated format. + [ICorDebugModuleBreakpoint Interface](icordebugmodulebreakpoint-interface.md)\ - Extends `ICorDebugBreakpoint` to provide access to specific modules. - + Extends `ICorDebugBreakpoint` to provide access to specific modules. + [ICorDebugModuleDebugEvent Interface](icordebugmoduledebugevent-interface.md)\ - Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support module-level events. **Available on .NET Native only.** - + Extends the [ICorDebugDebugEvent](icordebugdebugevent-interface.md) interface to support module-level events. **Available on .NET Native only.** + [ICorDebugModuleEnum Interface](icordebugmoduleenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugModule` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugModule` arrays. + [ICorDebugMutableDataTarget Interface](icordebugmutabledatatarget-interface.md)\ - Extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to support mutable data targets. - + Extends the [ICorDebugDataTarget](icordebugdatatarget-interface.md) interface to support mutable data targets. + [ICorDebugNativeFrame Interface](icordebugnativeframe-interface.md)\ - A specialized implementation of `ICorDebugFrame` used for native frames. - + A specialized implementation of `ICorDebugFrame` used for native frames. + [ICorDebugNativeFrame2 Interface](icordebugnativeframe2-interface.md)\ - Provides methods that test for child and parent frame relationships. - + Provides methods that test for child and parent frame relationships. + [ICorDebugObjectEnum Interface](icordebugobjectenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates arrays of objects by their relative virtual addresses (RVAs). - + Implements `ICorDebugEnum` methods, and enumerates arrays of objects by their relative virtual addresses (RVAs). + [ICorDebugObjectValue Interface](icordebugobjectvalue-interface.md)\ - A subclass of `ICorDebugValue` that represents a value that contains an object. - + A subclass of `ICorDebugValue` that represents a value that contains an object. + [ICorDebugObjectValue2 Interface](icordebugobjectvalue2-interface.md)\ - Extends `ICorDebugObjectValue` to support inheritance and overrides. - + Extends `ICorDebugObjectValue` to support inheritance and overrides. + [ICorDebugProcess Interface](icordebugprocess-interface.md)\ - Represents a process that is executing managed code. - + Represents a process that is executing managed code. + [ICorDebugProcess2 Interface](icordebugprocess2-interface1.md)\ - A logical extension of `ICorDebugProcess`. - + A logical extension of `ICorDebugProcess`. + [ICorDebugProcess3 Interface](icordebugprocess3-interface.md)\ Controls custom debugger notifications. [ICorDebugProcess4 Interface](icordebugprocess4-interface.md)\ Provides support for out of process execution control. - + [ICorDebugProcess5 Interface](icordebugprocess5-interface.md)\ - Extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to support access to the managed heap, to provide information about garbage collection of managed objects, and to determine whether a debugger loads images from the application's local native image cache. - + Extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to support access to the managed heap, to provide information about garbage collection of managed objects, and to determine whether a debugger loads images from the application's local native image cache. + [ICorDebugProcess6 Interface](icordebugprocess6-interface.md)\ - Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable features such as decoding managed debug events that are encoded in native exception debug events and virtual module splitting. **Available on .NET Native only.** - + Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable features such as decoding managed debug events that are encoded in native exception debug events and virtual module splitting. **Available on .NET Native only.** + [ICorDebugProcess7 Interface](icordebugprocess7-interface.md)\ - Provides a method that configures the debugger to handle in-memory metadata updates in the target process. - + Provides a method that configures the debugger to handle in-memory metadata updates in the target process. + [ICorDebugProcess8 Interface](icordebugprocess8-interface.md)\ - Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable or disable certain types of [ICorDebugManagedCallback2](icordebugmanagedcallback2-interface.md) exception callbacks. + Logically extends the [ICorDebugProcess](icordebugprocess-interface.md) interface to enable or disable certain types of [ICorDebugManagedCallback2](icordebugmanagedcallback2-interface.md) exception callbacks. [ICorDebugProcess11 Interface](icordebugprocess11-interface.md)\ - Provides a method that enumerates ranges of native memory that are used by the .NET runtime to store internal data structures that describe .NET types and methods. The information returned is the same information that would be shown by using the SOS `eeheap -loader` command. - + Provides a method that enumerates ranges of native memory that are used by the .NET runtime to store internal data structures that describe .NET types and methods. The information returned is the same information that would be shown by using the SOS `eeheap -loader` command. + [ICorDebugProcessEnum Interface](icordebugprocessenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugProcess` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugProcess` arrays. + [ICorDebugReferenceValue Interface](icordebugreferencevalue-interface.md)\ - A subclass of `ICorDebugValue` that supports reference types. - + A subclass of `ICorDebugValue` that supports reference types. + [ICorDebugRegisterSet Interface](icordebugregisterset-interface.md)\ - Represents the set of registers available on the machine that is currently executing code. - + Represents the set of registers available on the machine that is currently executing code. + [ICorDebugRegisterSet2 Interface](icordebugregisterset2-interface.md)\ - Extends the capabilities of `ICorDebugRegisterSet` for hardware platforms that have more than 64 registers. - + Extends the capabilities of `ICorDebugRegisterSet` for hardware platforms that have more than 64 registers. + [ICorDebugRemote Interface](icordebugremote-interface.md)\ - Provides the ability to launch or attach a managed debugger to a remote target process. - + Provides the ability to launch or attach a managed debugger to a remote target process. + [ICorDebugRemoteTarget Interface](icordebugremotetarget-interface.md)\ - Provides methods that enable you to debug Silverlight-based applications in the CLR environment. - + Provides methods that enable you to debug Silverlight-based applications in the CLR environment. + [ICorDebugRuntimeUnwindableFrame Interface](icordebugruntimeunwindableframe-interface.md)\ - Provides support for unmanaged methods that require the common language runtime (CLR) to unwind a frame. - + Provides support for unmanaged methods that require the common language runtime (CLR) to unwind a frame. + [ICorDebugStackWalk Interface](icordebugstackwalk-interface.md)\ - Provides methods for getting the managed methods, or frames, on a thread’s stack. - + Provides methods for getting the managed methods, or frames, on a thread’s stack. + [ICorDebugStaticFieldSymbol Interface](icordebugstaticfieldsymbol-interface.md)\ - Represents the debug symbol information for a static field. **Available on .NET Native only.** - + Represents the debug symbol information for a static field. **Available on .NET Native only.** + [ICorDebugStepper Interface](icordebugstepper-interface.md)\ - Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. - + Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. + [ICorDebugStepper2 Interface](icordebugstepper2-interface1.md)\ - Provides support for Just My Code (JMC) debugging. - + Provides support for Just My Code (JMC) debugging. + [ICorDebugStepperEnum Interface](icordebugstepperenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugStepper` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugStepper` arrays. + [ICorDebugStringValue Interface](icordebugstringvalue-interface.md)\ - A subclass of `ICorDebugHeapValue` that applies to string values. - + A subclass of `ICorDebugHeapValue` that applies to string values. + [ICorDebugSymbolProvider Interface](icordebugsymbolprovider-interface.md)\ - Provides methods that can be used to retrieve debug symbol information. **Available on .NET Native only.** - + Provides methods that can be used to retrieve debug symbol information. **Available on .NET Native only.** + [ICorDebugSymbolProvider2 Interface](icordebugsymbolprovider2-interface.md)\ - Logically extends the [ICorDebugSymbolProvider](icordebugsymbolprovider-interface.md) interface to retrieve additional debug symbol information. **Available on .NET Native only.** - + Logically extends the [ICorDebugSymbolProvider](icordebugsymbolprovider-interface.md) interface to retrieve additional debug symbol information. **Available on .NET Native only.** + [ICorDebugThread Interface](icordebugthread-interface.md)\ - Represents a thread in a process. The lifetime of an `ICorDebugThread` instance is the same as the lifetime of the thread it represents. - + Represents a thread in a process. The lifetime of an `ICorDebugThread` instance is the same as the lifetime of the thread it represents. + [ICorDebugThread2 Interface](icordebugthread2-interface.md)\ - Serves as a logical extension to `ICorDebugThread`. - + Serves as a logical extension to `ICorDebugThread`. + [ICorDebugThread3 Interface](icordebugthread3-interface.md)\ - Provides the entry point to the [ICorDebugStackWalk](icordebugstackwalk-interface.md) and corresponding interfaces. - + Provides the entry point to the [ICorDebugStackWalk](icordebugstackwalk-interface.md) and corresponding interfaces. + [ICorDebugThread4 Interface](icordebugthread4-interface.md)\ - Provides thread blocking information. - + Provides thread blocking information. + [ICorDebugThreadEnum Interface](icordebugthreadenum-interface1.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugThread` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugThread` arrays. + [ICorDebugType Interface](icordebugtype-interface.md)\ - Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugType` represents the instantiated generic type. - + Represents a type, which can be either basic or complex (that is, user-defined). If the type is generic, `ICorDebugType` represents the instantiated generic type. + [ICorDebugType2 Interface](icordebugtype2-interface.md)\ - Extends the [ICorDebugType](icordebugtype-interface.md) interface to retrieve the type identifier of a base type or complex (user-defined) type. - + Extends the [ICorDebugType](icordebugtype-interface.md) interface to retrieve the type identifier of a base type or complex (user-defined) type. + [ICorDebugTypeEnum Interface](icordebugtypeenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugType` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugType` arrays. + [ICorDebugUnmanagedCallback Interface](icordebugunmanagedcallback-interface.md)\ - Provides notification of native events that are not directly related to the CLR. - + Provides notification of native events that are not directly related to the CLR. + [ICorDebugValue](icordebugvalue-interface.md)\ - Represents a read or write value in the process being debugged. - + Represents a read or write value in the process being debugged. + [ICorDebugValue2](icordebugvalue2-interface.md)\ - Extends `ICorDebugValue` to provide support for `ICorDebugType`. - + Extends `ICorDebugValue` to provide support for `ICorDebugType`. + [ICorDebugValue3 Interface](icordebugvalue3-interface.md)\ - Extends the "ICorDebugValue" and "ICorDebugValue2" interfaces to provide support for arrays that are larger than 2 GB. - + Extends the "ICorDebugValue" and "ICorDebugValue2" interfaces to provide support for arrays that are larger than 2 GB. + [ICorDebugValueBreakpoint](icordebugvaluebreakpoint-interface.md)\ - Extends `ICorDebugBreakpoint` to provide access to specific values. - + Extends `ICorDebugBreakpoint` to provide access to specific values. + [ICorDebugValueEnum](icordebugvalueenum-interface.md)\ - Implements `ICorDebugEnum` methods, and enumerates `ICorDebugValue` arrays. - + Implements `ICorDebugEnum` methods, and enumerates `ICorDebugValue` arrays. + [ICorDebugVariableHome Interface](icordebugvariablehome-interface.md)\ - Represents a local variable or argument of a function. - + Represents a local variable or argument of a function. + [ICorDebugVariableHomeEnum Interface](icordebugvariablehomeenum-interface.md)\ - Provides an enumerator to the local variables and arguments in a function. - + Provides an enumerator to the local variables and arguments in a function. + [ICorDebugVariableSymbol Interface](icordebugvariablesymbol-interface.md)\ - Retrieves the debug symbol information for a variable. **Available on .NET Native only.** - + Retrieves the debug symbol information for a variable. **Available on .NET Native only.** + [ICorDebugVirtualUnwinder Interface](icordebugvirtualunwinder-interface.md)\ - Provides methods to help in stack unwinding. **Available on .NET Native only.** - + Provides methods to help in stack unwinding. **Available on .NET Native only.** + [ICorPublish Interface](icorpublish-interface.md)\ - Serves as the general interface for the publishing processes. - + Serves as the general interface for the publishing processes. + [ICorPublishAppDomain Interface](icorpublishappdomain-interface.md)\ - Represents and provides information about an application domain. - + Represents and provides information about an application domain. + [ICorPublishAppDomainEnum Interface](icorpublishappdomainenum-interface.md)\ - Provides methods that traverse a collection of `ICorPublishAppDomain` objects that currently exist within a process. - + Provides methods that traverse a collection of `ICorPublishAppDomain` objects that currently exist within a process. + [ICorPublishEnum Interface](icorpublishenum-interface.md)\ - Serves as the abstract base for publishing enumerators. - + Serves as the abstract base for publishing enumerators. + [ICorPublishProcess Interface](icorpublishprocess-interface.md)\ - Provides methods that access information about a process. - + Provides methods that access information about a process. + [ICorPublishProcessEnum Interface](icorpublishprocessenum-interface.md)\ - Provides methods that traverse a collection of `ICorPublishProcess` objects. + Provides methods that traverse a collection of `ICorPublishProcess` objects. [ISOSDacInterface Interface](isosdacinterface-interface.md)\ Provides helper methods to access data from `SOS`. @@ -451,8 +451,8 @@ This section describes the unmanaged interfaces that handle the debugging of a p [IXCLRDataProcess Interface](ixclrdataprocess-interface.md)\ Provides methods for querying information about a process. - -## Related Sections + +## Related Sections [Debugging Coclasses](debugging-coclasses.md)\ [Debugging Global Static Functions](debugging-global-static-functions.md)\ diff --git a/docs/framework/unmanaged-api/debugging/debugging-structures.md b/docs/framework/unmanaged-api/debugging/debugging-structures.md index da6a0a405f505..52d5c05cfde99 100644 --- a/docs/framework/unmanaged-api/debugging/debugging-structures.md +++ b/docs/framework/unmanaged-api/debugging/debugging-structures.md @@ -33,7 +33,7 @@ This section describes the unmanaged structures that the debugging API uses. Provides information about the layout of an array object in memory. [COR_DEBUG_IL_TO_NATIVE_MAP](cor-debug-il-to-native-map-structure.md) - Contains the offsets that are used to map Microsoft intermediate language (MSIL) code to native code. + Contains the offsets that are used to map common intermediate language (CIL) code to native code. [COR_DEBUG_STEP_RANGE](cor-debug-step-range-structure.md) Contains the offset information for a range of code. diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md index 304a9e41ac902..132db3e554f8a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-createbreakpoint-method.md @@ -2,54 +2,54 @@ description: "Learn more about: ICorDebugCode::CreateBreakpoint Method" title: "ICorDebugCode::CreateBreakpoint Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugCode.CreateBreakpoint" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugCode::CreateBreakpoint" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugCode::CreateBreakpoint method [.NET Framework debugging]" - "CreateBreakpoint method, ICorDebugCode interface [.NET Framework debugging]" ms.assetid: 46842618-0fe4-480b-871c-82fba82d23d9 -topic_type: +topic_type: - "apiref" --- # ICorDebugCode::CreateBreakpoint Method -Creates a breakpoint in this code segment at the specified offset. - -## Syntax - -```cpp -HRESULT CreateBreakpoint ( - [in] ULONG32 offset, - [out] ICorDebugFunctionBreakpoint **ppBreakpoint -); -``` - -## Parameters - - `offset` - [in] The offset at which to create the breakpoint. - - `ppBreakpoint` - [out] A pointer to the address of an "ICorDebugFunctionBreakpoint" object that represents the breakpoint. - -## Remarks - - Before the breakpoint is active, it must be added to the process object. - - If this code is Microsoft intermediate language (MSIL) code, and there is a just-in-time (JIT)-compiled, native version of the code, the breakpoint will be applied in the JIT-compiled code as well. (The same is true if the code is JIT-compiled later.) - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Creates a breakpoint in this code segment at the specified offset. + +## Syntax + +```cpp +HRESULT CreateBreakpoint ( + [in] ULONG32 offset, + [out] ICorDebugFunctionBreakpoint **ppBreakpoint +); +``` + +## Parameters + + `offset` + [in] The offset at which to create the breakpoint. + + `ppBreakpoint` + [out] A pointer to the address of an "ICorDebugFunctionBreakpoint" object that represents the breakpoint. + +## Remarks + + Before the breakpoint is active, it must be added to the process object. + + If this code is common intermediate language (CIL) code, and there is a just-in-time (JIT)-compiled, native version of the code, the breakpoint will be applied in the JIT-compiled code as well. (The same is true if the code is JIT-compiled later.) + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md index 3925ff60ded3e..0b8f0468a95d0 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-getiltonativemapping-method.md @@ -2,63 +2,63 @@ description: "Learn more about: ICorDebugCode::GetILToNativeMapping Method" title: "ICorDebugCode::GetILToNativeMapping Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugCode.GetILToNativeMapping" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugCode::GetILToNativeMapping" -helpviewer_keywords: +helpviewer_keywords: - "GetILToNativeMapping method, ICorDebugCode interface [.NET Framework debugging]" - "ICorDebugCode::GetILToNativeMapping method [.NET Framework debugging]" ms.assetid: a8ecd8c8-9627-4356-9c6f-bd05e24637c0 -topic_type: +topic_type: - "apiref" --- # ICorDebugCode::GetILToNativeMapping Method -Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from Microsoft intermediate language (MSIL) offsets to native offsets. - -## Syntax - -```cpp -HRESULT GetILToNativeMapping ( - [in] ULONG32 cMap, - [out] ULONG32 *pcMap, - [out, size_is(cMap), length_is(*pcMap)] - COR_DEBUG_IL_TO_NATIVE_MAP map[] -); -``` - -## Parameters - - `cMap` - [in] The size of the `map` array. - - `pcMap` - [out] A pointer to the actual number of elements returned in the `map` array. - - `map` - [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which represents a mapping from an MSIL offset to a native offset. - - There is no ordering to the array of elements returned. - -## Remarks - - The `GetILToNativeMapping` method returns meaningful results only if this "ICorDebugCode" instance represents native code that was just-in-time (JIT) compiled from MSIL code. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from common intermediate language (CIL) offsets to native offsets. + +## Syntax + +```cpp +HRESULT GetILToNativeMapping ( + [in] ULONG32 cMap, + [out] ULONG32 *pcMap, + [out, size_is(cMap), length_is(*pcMap)] + COR_DEBUG_IL_TO_NATIVE_MAP map[] +); +``` + +## Parameters + + `cMap` + [in] The size of the `map` array. + + `pcMap` + [out] A pointer to the actual number of elements returned in the `map` array. + + `map` + [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which represents a mapping from a CIL offset to a native offset. + + There is no ordering to the array of elements returned. + +## Remarks + + The `GetILToNativeMapping` method returns meaningful results only if this "ICorDebugCode" instance represents native code that was just-in-time (JIT) compiled from CIL code. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [ICorDebugCode Interface](icordebugcode-interface1.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md b/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md index fbb0362e51295..f72fa26975621 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-interface1.md @@ -2,55 +2,55 @@ description: "Learn more about: ICorDebugCode Interface" title: "ICorDebugCode Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugCode" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugCode" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugCode interface [.NET Framework debugging]" ms.assetid: 7bd14fb6-8b54-4484-a891-e3c21859c019 -topic_type: +topic_type: - "apiref" --- # ICorDebugCode Interface -Represents a segment of either Microsoft intermediate language (MSIL) code or native code. - -## Methods - -|Method|Description| -|------------|-----------------| -|[CreateBreakpoint Method](icordebugcode-createbreakpoint-method.md)|Creates a breakpoint at the specified offset.| -|[GetAddress Method](icordebugcode-getaddress-method.md)|Gets the relative virtual address (RVA) of the code segment that this `ICorDebugCode` represents.| -|[GetCode Method](icordebugcode-getcode-method.md)|Gets all the code for the specified function, formatted for disassembly. This method has been deprecated; use [ICorDebugCode2::GetCodeChunks](icordebugcode2-getcodechunks-method.md) instead.| -|[GetEnCRemapSequencePoints Method](icordebugcode-getencremapsequencepoints-method.md)|Not implemented.| -|[GetFunction Method](icordebugcode-getfunction-method.md)|Gets the "ICorDebugFunction" associated with this `ICorDebugCode`.| -|[GetILToNativeMapping Method](icordebugcode-getiltonativemapping-method.md)|Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from MSIL offsets to native offsets.| -|[GetSize Method](icordebugcode-getsize-method.md)|Gets the size, in bytes, of the binary code represented by this `ICorDebugCode`.| -|[GetVersionNumber Method](icordebugcode-getversionnumber-method.md)|Gets the one-based number that identifies the version of the code that this `ICorDebugCode` represents.| -|[IsIL Method](icordebugcode-isil-method.md)|Gets a value that indicates whether this `ICorDebugCode` is compiled in MSIL.| - -## Remarks - - `ICorDebugCode` can represent either MSIL or native code. An "ICorDebugFunction" object that represents MSIL code can have either zero or one `ICorDebugCode` objects associated with it. An "ICorDebugFunction" object that represents native code can have any number of `ICorDebugCode` objects associated with it. - +Represents a segment of either common intermediate language (CIL) code or native code. + +## Methods + +|Method|Description| +|------------|-----------------| +|[CreateBreakpoint Method](icordebugcode-createbreakpoint-method.md)|Creates a breakpoint at the specified offset.| +|[GetAddress Method](icordebugcode-getaddress-method.md)|Gets the relative virtual address (RVA) of the code segment that this `ICorDebugCode` represents.| +|[GetCode Method](icordebugcode-getcode-method.md)|Gets all the code for the specified function, formatted for disassembly. This method has been deprecated; use [ICorDebugCode2::GetCodeChunks](icordebugcode2-getcodechunks-method.md) instead.| +|[GetEnCRemapSequencePoints Method](icordebugcode-getencremapsequencepoints-method.md)|Not implemented.| +|[GetFunction Method](icordebugcode-getfunction-method.md)|Gets the "ICorDebugFunction" associated with this `ICorDebugCode`.| +|[GetILToNativeMapping Method](icordebugcode-getiltonativemapping-method.md)|Gets an array of "COR_DEBUG_IL_TO_NATIVE_MAP" instances that represent mappings from CIL offsets to native offsets.| +|[GetSize Method](icordebugcode-getsize-method.md)|Gets the size, in bytes, of the binary code represented by this `ICorDebugCode`.| +|[GetVersionNumber Method](icordebugcode-getversionnumber-method.md)|Gets the one-based number that identifies the version of the code that this `ICorDebugCode` represents.| +|[IsIL Method](icordebugcode-isil-method.md)|Gets a value that indicates whether this `ICorDebugCode` is compiled in CIL.| + +## Remarks + + `ICorDebugCode` can represent either CIL or native code. An "ICorDebugFunction" object that represents CIL code can have either zero or one `ICorDebugCode` objects associated with it. An "ICorDebugFunction" object that represents native code can have any number of `ICorDebugCode` objects associated with it. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [ICorDebugCode3 Interface](icordebugcode3-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md index fdee38ef19e8d..e80d780c4601a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode-isil-method.md @@ -19,7 +19,7 @@ topic_type: --- # ICorDebugCode::IsIL Method -Gets a value that indicates whether this "ICorDebugCode" represents code that was compiled in Microsoft intermediate language (MSIL). +Gets a value that indicates whether this "ICorDebugCode" represents code that was compiled in common intermediate language (CIL). ## Syntax @@ -31,8 +31,8 @@ HRESULT IsIL ( ## Parameters -`pbIL` -[out] `true` if this `ICorDebugCode` represents code that was compiled in MSIL; otherwise, `false`. +`pbIL` +[out] `true` if this `ICorDebugCode` represents code that was compiled in CIL; otherwise, `false`. ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md b/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md index 7035b85aaf94e..a1ce1abcf4990 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugcode2-getcodechunks-method.md @@ -34,18 +34,18 @@ HRESULT GetCodeChunks ( ## Parameters -`cbufSize` +`cbufSize` [in] Size of the `chunks` array. -`pcnumChunks` +`pcnumChunks` [out] The number of chunks returned in the `chunks` array. -`chunks` +`chunks` [out] An array of "CodeChunkInfo" structures, each of which represents a single chunk of code. If the value of `cbufSize` is 0, this parameter can be null. ## Remarks -The code chunks will never overlap, and they will follow the order in which they would have been concatenated by [ICorDebugCode::GetCode](icordebugcode-getcode-method.md). A Microsoft intermediate language (MSIL) code object in the .NET Framework version 2.0 will comprise a single code chunk. +The code chunks will never overlap, and they will follow the order in which they would have been concatenated by [ICorDebugCode::GetCode](icordebugcode-getcode-method.md). A common intermediate language (CIL) code object in the .NET Framework version 2.0 will comprise a single code chunk. ## Requirements diff --git a/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md b/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md index 8d098e5e64bcb..3b914e360a0e7 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugfunction-getilcode-method.md @@ -2,48 +2,48 @@ description: "Learn more about: ICorDebugFunction::GetILCode Method" title: "ICorDebugFunction::GetILCode Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugFunction.GetILCode" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugFunction::GetILCode" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugFunction::GetILCode method [.NET Framework debugging]" - "GetILCode method [.NET Framework debugging]" ms.assetid: f794dd47-a7cd-47f6-96e9-a41a4dae8e72 -topic_type: +topic_type: - "apiref" --- # ICorDebugFunction::GetILCode Method -Gets the ICorDebugCode instance that represents the Microsoft intermediate language (MSIL) code associated with this ICorDebugFunction object. - -## Syntax - -```cpp -HRESULT GetILCode ( - [out] ICorDebugCode **ppCode -); -``` - -## Parameters - - `ppCode` - [out] A pointer to the `ICorDebugCode` instance, or null, if the function was not compiled into MSIL. - -## Remarks - - If Edit and Continue has been allowed on this function, the `GetILCode` method will get the MSIL code corresponding to this function's edited version of the code in the common language runtime (CLR). - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the ICorDebugCode instance that represents the common intermediate language (CIL) code associated with this ICorDebugFunction object. + +## Syntax + +```cpp +HRESULT GetILCode ( + [out] ICorDebugCode **ppCode +); +``` + +## Parameters + + `ppCode` + [out] A pointer to the `ICorDebugCode` instance, or null, if the function was not compiled into CIL. + +## Remarks + + If Edit and Continue has been allowed on this function, the `GetILCode` method will get the CIL code corresponding to this function's edited version of the code in the common language runtime (CLR). + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md b/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md index 3c6d5022a687c..2c7490dcd1c21 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugfunction-getnativecode-method.md @@ -2,48 +2,48 @@ description: "Learn more about: ICorDebugFunction::GetNativeCode Method" title: "ICorDebugFunction::GetNativeCode Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugFunction.GetNativeCode" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugFunction::GetNativeCode" -helpviewer_keywords: +helpviewer_keywords: - "GetNativeCode method [.NET Framework debugging]" - "ICorDebugFunction::GetNativeCode method [.NET Framework debugging]" ms.assetid: c8a34916-0eef-4987-8d29-c8bcb4be9cf6 -topic_type: +topic_type: - "apiref" --- # ICorDebugFunction::GetNativeCode Method -Gets the native code for the function that is represented by this ICorDebugFunction instance. - -## Syntax - -```cpp -HRESULT GetNativeCode ( - [out] ICorDebugCode **ppCode -); -``` - -## Parameters - - `ppCode` - [out] A pointer to the ICorDebugCode instance that represents the native code for this function, or null, if this function is Microsoft intermediate language (MSIL) code that has not been just-in-time (JIT) compiled. - -## Remarks - - If the function that is represented by this `ICorDebugFunction` instance has been JIT-compiled more than once, as in the case of generic types, `GetNativeCode` returns a random native code object. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the native code for the function that is represented by this ICorDebugFunction instance. + +## Syntax + +```cpp +HRESULT GetNativeCode ( + [out] ICorDebugCode **ppCode +); +``` + +## Parameters + + `ppCode` + [out] A pointer to the ICorDebugCode instance that represents the native code for this function, or null, if this function is common intermediate language (CIL) code that has not been just-in-time (JIT) compiled. + +## Remarks + + If the function that is represented by this `ICorDebugFunction` instance has been JIT-compiled more than once, as in the case of generic types, `GetNativeCode` returns a random native code object. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md b/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md index e4f59d869a1c8..3cbbdfc8e1d6c 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md +++ b/docs/framework/unmanaged-api/debugging/icordebugfunction-interface1.md @@ -2,60 +2,60 @@ description: "Learn more about: ICorDebugFunction Interface" title: "ICorDebugFunction Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugFunction" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugFunction" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugFunction interface [.NET Framework debugging]" ms.assetid: 783faea9-8083-41c1-b04a-51a81ac4c8f3 -topic_type: +topic_type: - "apiref" --- # ICorDebugFunction Interface -Represents a managed function or method. - -## Methods - -|Method|Description| -|------------|-----------------| -|[CreateBreakpoint Method](icordebugfunction-createbreakpoint-method.md)|Creates a breakpoint at the beginning of this function.| -|[GetClass Method](icordebugfunction-getclass-method.md)|Gets an ICorDebugClass object that represents the class this function is a member of.| -|[GetCurrentVersionNumber Method](icordebugfunction-getcurrentversionnumber-method.md)|Gets the version number of the latest edit made to this function.| -|[GetILCode Method](icordebugfunction-getilcode-method.md)|Gets the Microsoft intermediate language (MSIL) code for this function.| -|[GetLocalVarSigToken Method](icordebugfunction-getlocalvarsigtoken-method.md)|Gets the metadata token for the local variable signature of the function that is represented by this `ICorDebugFunction` instance.| -|[GetModule Method](icordebugfunction-getmodule-method.md)|Gets the module in which this function is defined.| -|[GetNativeCode Method](icordebugfunction-getnativecode-method.md)|Gets the native code for this function.| -|[GetToken Method](icordebugfunction-gettoken-method.md)|Gets the metadata token for this function.| - -## Remarks - - The `ICorDebugFunction` interface does not represent a function with generic type parameters. For example, an `ICorDebugFunction` instance would represent `Func` but not `Func`. Call [ICorDebugILFrame2::EnumerateTypeParameters](icordebugilframe2-enumeratetypeparameters-method.md) to get the generic type parameters. - - The relationship between a method's metadata token, `mdMethodDef`, and a method's `ICorDebugFunction` object is dependent upon whether Edit and Continue is allowed on the function: - -- If Edit and Continue is not allowed on the function, a one-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function has one `ICorDebugFunction` object and one `mdMethodDef` token. - -- If Edit and Continue is allowed on the function, a many-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function may have many instances of `ICorDebugFunction`, one for each version of the function, but only one `mdMethodDef` token. - +Represents a managed function or method. + +## Methods + +|Method|Description| +|------------|-----------------| +|[CreateBreakpoint Method](icordebugfunction-createbreakpoint-method.md)|Creates a breakpoint at the beginning of this function.| +|[GetClass Method](icordebugfunction-getclass-method.md)|Gets an ICorDebugClass object that represents the class this function is a member of.| +|[GetCurrentVersionNumber Method](icordebugfunction-getcurrentversionnumber-method.md)|Gets the version number of the latest edit made to this function.| +|[GetILCode Method](icordebugfunction-getilcode-method.md)|Gets the common intermediate language (CIL) code for this function.| +|[GetLocalVarSigToken Method](icordebugfunction-getlocalvarsigtoken-method.md)|Gets the metadata token for the local variable signature of the function that is represented by this `ICorDebugFunction` instance.| +|[GetModule Method](icordebugfunction-getmodule-method.md)|Gets the module in which this function is defined.| +|[GetNativeCode Method](icordebugfunction-getnativecode-method.md)|Gets the native code for this function.| +|[GetToken Method](icordebugfunction-gettoken-method.md)|Gets the metadata token for this function.| + +## Remarks + + The `ICorDebugFunction` interface does not represent a function with generic type parameters. For example, an `ICorDebugFunction` instance would represent `Func` but not `Func`. Call [ICorDebugILFrame2::EnumerateTypeParameters](icordebugilframe2-enumeratetypeparameters-method.md) to get the generic type parameters. + + The relationship between a method's metadata token, `mdMethodDef`, and a method's `ICorDebugFunction` object is dependent upon whether Edit and Continue is allowed on the function: + +- If Edit and Continue is not allowed on the function, a one-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function has one `ICorDebugFunction` object and one `mdMethodDef` token. + +- If Edit and Continue is allowed on the function, a many-to-one relationship exists between the `ICorDebugFunction` object and the `mdMethodDef` token. That is, the function may have many instances of `ICorDebugFunction`, one for each version of the function, but only one `mdMethodDef` token. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md index 355e3292e7af9..7a18dd1768c28 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-cansetip-method.md @@ -2,48 +2,48 @@ description: "Learn more about: ICorDebugILFrame::CanSetIP Method" title: "ICorDebugILFrame::CanSetIP Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.CanSetIP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::CanSetIP" -helpviewer_keywords: +helpviewer_keywords: - "CanSetIP method, ICorDebugILFrame interface [.NET Framework debugging]" - "ICorDebugILFrame::CanSetIP method [.NET Framework debugging]" ms.assetid: 16caf02f-c71e-486c-90b0-f0e54357d8f0 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::CanSetIP Method -Gets an HRESULT that indicates whether it is safe to set the instruction pointer to the specified offset location in Microsoft Intermediate Language (MSIL) code. - -## Syntax - -```cpp -HRESULT CanSetIP ( - [in] ULONG32 nOffset -); -``` - -## Parameters - - `nOffset` - [in] The desired setting for the instruction pointer. - -## Remarks - - Use the `CanSetIP` method before calling the [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md) method. If `CanSetIP` returns any HRESULT other than S_OK, you can still invoke `ICorDebugILFrame::SetIP`, but there is no guarantee that the debugger will continue the safe and correct execution of the code being debugged. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug,h - - **Library:** CorGuids.lib - +Gets an HRESULT that indicates whether it is safe to set the instruction pointer to the specified offset location in common intermediate language (CIL) code. + +## Syntax + +```cpp +HRESULT CanSetIP ( + [in] ULONG32 nOffset +); +``` + +## Parameters + + `nOffset` + [in] The desired setting for the instruction pointer. + +## Remarks + + Use the `CanSetIP` method before calling the [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md) method. If `CanSetIP` returns any HRESULT other than S_OK, you can still invoke `ICorDebugILFrame::SetIP`, but there is no guarantee that the debugger will continue the safe and correct execution of the code being debugged. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug,h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md index 231d21d91f8b5..0eb22accd3e54 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-getargument-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugILFrame::GetArgument Method" title: "ICorDebugILFrame::GetArgument Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.GetArgument" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::GetArgument" -helpviewer_keywords: +helpviewer_keywords: - "GetArgument method [.NET Framework debugging]" - "ICorDebugILFrame::GetArgument method [.NET Framework debugging]" ms.assetid: 4e2fd423-f643-4c27-ba5f-41b5ebc3b416 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::GetArgument Method -Gets the value of the specified argument in this Microsoft intermediate language (MSIL) stack frame. - -## Syntax - -```cpp -HRESULT GetArgument ( - [in] DWORD dwIndex, - [out] ICorDebugValue **ppValue -); -``` - -## Parameters - - `dwIndex` - [in] The index of the argument in this MSIL stack frame. - - `ppValue` - [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. - -## Remarks - - The `GetArgument` method can be used either in an MSIL stack frame or in a just-in-time (JIT) compiled frame. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the value of the specified argument in this common intermediate language (CIL) stack frame. + +## Syntax + +```cpp +HRESULT GetArgument ( + [in] DWORD dwIndex, + [out] ICorDebugValue **ppValue +); +``` + +## Parameters + + `dwIndex` + [in] The index of the argument in this CIL stack frame. + + `ppValue` + [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. + +## Remarks + + The `GetArgument` method can be used either in an CIL stack frame or in a just-in-time (JIT) compiled frame. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md index 2ec51e2306579..af89059646cfa 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-getip-method.md @@ -2,54 +2,54 @@ description: "Learn more about: ICorDebugILFrame::GetIP Method" title: "ICorDebugILFrame::GetIP Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.GetIP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::GetIP" -helpviewer_keywords: +helpviewer_keywords: - "GetIP method, ICorDebugILFrame interface [.NET Framework debugging]" - "ICorDebugILFrame::GetIP method [.NET Framework debugging]" ms.assetid: 18217ba1-1776-4297-a3b9-f77e64b0fead -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::GetIP Method -Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained. - -## Syntax - -```cpp -HRESULT GetIP ( +Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained. + +## Syntax + +```cpp +HRESULT GetIP ( [out] ULONG32 *pnOffset, - [out] CorDebugMappingResult *pMappingResult -); -``` - -## Parameters - - `pnOffset` - [out] The value of the instruction pointer. - - `pMappingResult` - [out] A pointer to a bitwise combination of the CorDebugMappingResult enumeration values that describe how the value of the instruction pointer was obtained. - -## Remarks - - The value of the instruction pointer is the stack frame's offset into the function's Microsoft intermediate language (MSIL) code. If the stack frame is active, this address is the next instruction to execute. If the stack frame is not active, this address is the next instruction to execute when the stack frame is reactivated. - - If this frame is a just-in-time (JIT) compiled frame, the value of the instruction pointer will be determined by mapping backwards from the actual native instruction pointer, so the value may be only approximate. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - + [out] CorDebugMappingResult *pMappingResult +); +``` + +## Parameters + + `pnOffset` + [out] The value of the instruction pointer. + + `pMappingResult` + [out] A pointer to a bitwise combination of the CorDebugMappingResult enumeration values that describe how the value of the instruction pointer was obtained. + +## Remarks + + The value of the instruction pointer is the stack frame's offset into the function's common intermediate language (CIL) code. If the stack frame is active, this address is the next instruction to execute. If the stack frame is not active, this address is the next instruction to execute when the stack frame is reactivated. + + If this frame is a just-in-time (JIT) compiled frame, the value of the instruction pointer will be determined by mapping backwards from the actual native instruction pointer, so the value may be only approximate. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md index 7798a00d5ddb8..dd583d620abdd 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-getlocalvariable-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugILFrame::GetLocalVariable Method" title: "ICorDebugILFrame::GetLocalVariable Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.GetLocalVariable" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::GetLocalVariable" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame::GetLocalVariable method [.NET Framework debugging]" - "GetLocalVariable method [.NET Framework debugging]" ms.assetid: c8706356-d50b-4f87-a40c-39c3b7f4fd38 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::GetLocalVariable Method -Gets the value of the specified local variable in this Microsoft intermediate language (MSIL) stack frame. - -## Syntax - -```cpp -HRESULT GetLocalVariable ( - [in] DWORD dwIndex, - [out] ICorDebugValue **ppValue -); -``` - -## Parameters - - `dwIndex` - [in] The index of the local variable in this MSIL stack frame. - - `ppValue` - [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. - -## Remarks - - The `GetLocalVariable` method can be used either in an MSIL stack frame or in a just-in-time (JIT) compiled frame. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the value of the specified local variable in this common intermediate language (CIL) stack frame. + +## Syntax + +```cpp +HRESULT GetLocalVariable ( + [in] DWORD dwIndex, + [out] ICorDebugValue **ppValue +); +``` + +## Parameters + + `dwIndex` + [in] The index of the local variable in this CIL stack frame. + + `ppValue` + [out] A pointer to the address of an ICorDebugValue object that represents the retrieved value. + +## Remarks + + The `GetLocalVariable` method can be used either in an CIL stack frame or in a just-in-time (JIT) compiled frame. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md index c49ca069afc8f..b7aaa69d24338 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-interface.md @@ -2,55 +2,55 @@ description: "Learn more about: ICorDebugILFrame Interface" title: "ICorDebugILFrame Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame interface [.NET Framework debugging]" ms.assetid: d5cf5056-da4d-4629-914d-afe42a5393df -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame Interface -Represents a stack frame of Microsoft intermediate language (MSIL) code. This interface is a subclass of the ICorDebugFrame interface. - -## Methods - -|Method|Description| -|------------|-----------------| -|[CanSetIP Method](icordebugilframe-cansetip-method.md)|Gets a value that indicates whether it is safe to set the instruction pointer to the specified offset location.| -|[EnumerateArguments Method](icordebugilframe-enumeratearguments-method.md)|Gets an enumerator for the arguments in this frame.| -|[EnumerateLocalVariables Method](icordebugilframe-enumeratelocalvariables-method.md)|Gets an enumerator for the local variables in this frame.| -|[GetArgument Method](icordebugilframe-getargument-method.md)|Gets the value of the specified argument in this MSIL stack frame.| -|[GetIP Method](icordebugilframe-getip-method.md)|Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained.| -|[GetLocalVariable Method](icordebugilframe-getlocalvariable-method.md)|Gets the value of the specified local variable in this MSIL stack frame.| -|[GetStackDepth Method](icordebugilframe-getstackdepth-method.md)|Not implemented.| -|[GetStackValue Method](icordebugilframe-getstackvalue-method.md)|Not implemented.| -|[SetIP Method](icordebugilframe-setip-method.md)|Sets the instruction pointer to the specified offset location in the MSIL code.| - -## Remarks - - The `ICorDebugILFrame` interface is a specialized ICorDebugFrame interface. It is used either for MSIL code frames or for just-in-time (JIT) compiled frames. The JIT-compiled frames implement both the `ICorDebugILFrame` interface and the ICorDebugNativeFrame interface. - +Represents a stack frame of common intermediate language (CIL) code. This interface is a subclass of the ICorDebugFrame interface. + +## Methods + +|Method|Description| +|------------|-----------------| +|[CanSetIP Method](icordebugilframe-cansetip-method.md)|Gets a value that indicates whether it is safe to set the instruction pointer to the specified offset location.| +|[EnumerateArguments Method](icordebugilframe-enumeratearguments-method.md)|Gets an enumerator for the arguments in this frame.| +|[EnumerateLocalVariables Method](icordebugilframe-enumeratelocalvariables-method.md)|Gets an enumerator for the local variables in this frame.| +|[GetArgument Method](icordebugilframe-getargument-method.md)|Gets the value of the specified argument in this CIL stack frame.| +|[GetIP Method](icordebugilframe-getip-method.md)|Gets the value of the instruction pointer and a bitwise combination value that describes how the value of the instruction pointer was obtained.| +|[GetLocalVariable Method](icordebugilframe-getlocalvariable-method.md)|Gets the value of the specified local variable in this CIL stack frame.| +|[GetStackDepth Method](icordebugilframe-getstackdepth-method.md)|Not implemented.| +|[GetStackValue Method](icordebugilframe-getstackvalue-method.md)|Not implemented.| +|[SetIP Method](icordebugilframe-setip-method.md)|Sets the instruction pointer to the specified offset location in the CIL code.| + +## Remarks + + The `ICorDebugILFrame` interface is a specialized ICorDebugFrame interface. It is used either for CIL code frames or for just-in-time (JIT) compiled frames. The JIT-compiled frames implement both the `ICorDebugILFrame` interface and the ICorDebugNativeFrame interface. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md index 76924f05ee023..8d570e0e8b6eb 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe-setip-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugILFrame::SetIP Method" title: "ICorDebugILFrame::SetIP Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame.SetIP" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame::SetIP" -helpviewer_keywords: +helpviewer_keywords: - "SetIP method, ICorDebugILFrame interface [.NET Framework debugging]" - "ICorDebugILFrame::SetIP method [.NET Framework debugging]" ms.assetid: 23f38dc1-85e4-4263-9235-2d05bbb6a833 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame::SetIP Method -Sets the instruction pointer to the specified offset location in the Microsoft intermediate language (MSIL) code. - -## Syntax - -```cpp -HRESULT SetIP ( - [in] ULONG32 nOffset -); -``` - -## Parameters - - `nOffset` - The offset location in the MSIL code. - -## Remarks - - Calls to `SetIP` immediately invalidate all frames and chains for the current thread. If the debugger needs frame information after a call to `SetIP`, it must perform a new stack trace. - - [ICorDebug](icordebug-interface.md) will attempt to keep the stack frame in a valid state. However, even if the frame is in a valid state, there still may be problems such as uninitialized local variables. The caller is responsible for ensuring the coherency of the running program. - - On 64-bit platforms, the instruction pointer cannot be moved out of a `catch` or `finally` block. If `SetIP` is called to make such a move on a 64-bit platform, it will return an HRESULT indicating failure. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Sets the instruction pointer to the specified offset location in the common intermediate language (CIL) code. + +## Syntax + +```cpp +HRESULT SetIP ( + [in] ULONG32 nOffset +); +``` + +## Parameters + + `nOffset` + The offset location in the CIL code. + +## Remarks + + Calls to `SetIP` immediately invalidate all frames and chains for the current thread. If the debugger needs frame information after a call to `SetIP`, it must perform a new stack trace. + + [ICorDebug](icordebug-interface.md) will attempt to keep the stack frame in a valid state. However, even if the frame is in a valid state, there still may be problems such as uninitialized local variables. The caller is responsible for ensuring the coherency of the running program. + + On 64-bit platforms, the instruction pointer cannot be moved out of a `catch` or `finally` block. If `SetIP` is called to make such a move on a 64-bit platform, it will return an HRESULT indicating failure. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md b/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md index 55eec602ff0dd..a60901785989e 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe2-interface.md @@ -2,46 +2,46 @@ description: "Learn more about: ICorDebugILFrame2 Interface" title: "ICorDebugILFrame2 Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame2" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame2" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame2 interface [.NET Framework debugging]" ms.assetid: f94b9d53-d8f8-4424-a95e-53a1bfd26e4a -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame2 Interface -A logical extension of the ICorDebugILFrame interface. - -## Methods - -|Method|Description| -|------------|-----------------| -|[EnumerateTypeParameters Method](icordebugilframe2-enumeratetypeparameters-method.md)|Gets an ICorDebugTypeEnum object that contains the parameters in this frame.| -|[RemapFunction Method](icordebugilframe2-remapfunction-method.md)|Remaps an edited function by specifying the new MSIL offset.| - -## Remarks - +A logical extension of the ICorDebugILFrame interface. + +## Methods + +|Method|Description| +|------------|-----------------| +|[EnumerateTypeParameters Method](icordebugilframe2-enumeratetypeparameters-method.md)|Gets an ICorDebugTypeEnum object that contains the parameters in this frame.| +|[RemapFunction Method](icordebugilframe2-remapfunction-method.md)|Remaps an edited function by specifying the new CIL offset.| + +## Remarks + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md b/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md index 7949a3096b15c..44fa2e99b611c 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugilframe2-remapfunction-method.md @@ -2,59 +2,59 @@ description: "Learn more about: ICorDebugILFrame2::RemapFunction Method" title: "ICorDebugILFrame2::RemapFunction Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugILFrame2.RemapFunction" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugILFrame2::RemapFunction" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugILFrame2::RemapFunction method [.NET Framework debugging]" - "RemapFunction method [.NET Framework debugging]" ms.assetid: dd639ba0-f77b-426d-9ff6-f92706840348 -topic_type: +topic_type: - "apiref" --- # ICorDebugILFrame2::RemapFunction Method -Remaps an edited function by specifying the new Microsoft intermediate language (MSIL) offset - -## Syntax - -```cpp -HRESULT RemapFunction ( - [in] ULONG32 newILOffset -); -``` - -## Parameters - - `newILOffset` - [in] The stack frame's new MSIL offset at which the instruction pointer should be placed. This value must be a sequence point. - - It is the caller’s responsibility to ensure the validity of this value. For example, the MSIL offset is not valid if it is outside the bounds of the function. - -## Remarks - - When a frame’s function has been edited, the debugger can call the `RemapFunction` method to swap in the latest version of the frame's function so it can be executed. The code execution will begin at the given MSIL offset. - +Remaps an edited function by specifying the new common intermediate language (CIL) offset + +## Syntax + +```cpp +HRESULT RemapFunction ( + [in] ULONG32 newILOffset +); +``` + +## Parameters + + `newILOffset` + [in] The stack frame's new CIL offset at which the instruction pointer should be placed. This value must be a sequence point. + + It is the caller’s responsibility to ensure the validity of this value. For example, the CIL offset is not valid if it is outside the bounds of the function. + +## Remarks + + When a frame’s function has been edited, the debugger can call the `RemapFunction` method to swap in the latest version of the frame's function so it can be executed. The code execution will begin at the given CIL offset. + > [!NOTE] -> Calling `RemapFunction`, like calling [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md), will immediately invalidate all debugging interfaces that are related to generating a stack trace for the thread. These interfaces include [ICorDebugChain](icordebugchain-interface.md), ICorDebugILFrame, ICorDebugInternalFrame, and ICorDebugNativeFrame. - - The `RemapFunction` method can be called only in the context of the current frame, and only in one of the following cases: - -- After receipt of a [ICorDebugManagedCallback2::FunctionRemapOpportunity](icordebugmanagedcallback2-functionremapopportunity-method.md) callback that has not yet been continued. - -- While code execution is stopped because of an [ICorDebugManagedCallback::EditAndContinueRemap](icordebugmanagedcallback-editandcontinueremap-method.md) event for this frame. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +> Calling `RemapFunction`, like calling [ICorDebugILFrame::SetIP](icordebugilframe-setip-method.md), will immediately invalidate all debugging interfaces that are related to generating a stack trace for the thread. These interfaces include [ICorDebugChain](icordebugchain-interface.md), ICorDebugILFrame, ICorDebugInternalFrame, and ICorDebugNativeFrame. + + The `RemapFunction` method can be called only in the context of the current frame, and only in one of the following cases: + +- After receipt of a [ICorDebugManagedCallback2::FunctionRemapOpportunity](icordebugmanagedcallback2-functionremapopportunity-method.md) callback that has not yet been continued. + +- While code execution is stopped because of an [ICorDebugManagedCallback::EditAndContinueRemap](icordebugmanagedcallback-editandcontinueremap-method.md) event for this frame. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md index f4d59f1bbc544..d7ecf3c258070 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-exception-method.md @@ -2,83 +2,83 @@ description: "Learn more about: ICorDebugManagedCallback2::Exception Method" title: "ICorDebugManagedCallback2::Exception Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugManagedCallback2.Exception" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugManagedCallback2::Exception" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugManagedCallback2::Exception method [.NET Framework debugging]" - "Exception method, ICorDebugManagedCallback2 interface [.NET Framework debugging]" ms.assetid: 78b0f14f-2fae-4e63-8412-4df119ee8468 -topic_type: +topic_type: - "apiref" --- # ICorDebugManagedCallback2::Exception Method -Notifies the debugger that a search for an exception handler has started. - -## Syntax - -```cpp -HRESULT Exception ( - [in] ICorDebugAppDomain *pAppDomain, - [in] ICorDebugThread *pThread, - [in] ICorDebugFrame *pFrame, - [in] ULONG32 nOffset, - [in] CorDebugExceptionCallbackType dwEventType, - [in] DWORD dwFlags -); -``` - -## Parameters - - `pAppDomain` - [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the thread on which the exception was thrown. - - `pThread` - [in] A pointer to an ICorDebugThread object that represents the thread on which the exception was thrown. - - `pFrame` - [in] A pointer to an ICorDebugFrame object that represents a frame, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. - - `nOffset` - [in] An integer that specifies an offset, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. - - `dwEventType` - [in] A value of the CorDebugExceptionCallbackType enumeration that specifies the type of this exception callback. - - `dwFlags` - [in] A value of the [CorDebugExceptionFlags](cordebugexceptionflags-enumeration.md) enumeration that specifies additional information about the exception - -## Remarks - - The `Exception` callback is called at various points during the search phase of the exception-handling process. That is, it can be called more than once while unwinding an exception. - - The exception being processed can be retrieved from the ICorDebugThread object referenced by the `pThread` parameter. - - The particular frame and offset are determined by the `dwEventType` parameter as follows: - -|Value of `dwEventType`|Value of `pFrame`|Value of `nOffset`| -|----------------------------|-----------------------|------------------------| -|DEBUG_EXCEPTION_FIRST_CHANCE|The frame that threw the exception.|The instruction pointer in the frame.| -|DEBUG_EXCEPTION_USER_FIRST_CHANCE|The user-code frame closest to the point of the thrown exception.|The instruction pointer in the frame.| -|DEBUG_EXCEPTION_CATCH_HANDLER_FOUND|The frame that contains the catch handler.|The Microsoft intermediate language (MSIL) offset of the beginning of the catch handler.| -|DEBUG_EXCEPTION_UNHANDLED|NULL|Undefined.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Notifies the debugger that a search for an exception handler has started. + +## Syntax + +```cpp +HRESULT Exception ( + [in] ICorDebugAppDomain *pAppDomain, + [in] ICorDebugThread *pThread, + [in] ICorDebugFrame *pFrame, + [in] ULONG32 nOffset, + [in] CorDebugExceptionCallbackType dwEventType, + [in] DWORD dwFlags +); +``` + +## Parameters + + `pAppDomain` + [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the thread on which the exception was thrown. + + `pThread` + [in] A pointer to an ICorDebugThread object that represents the thread on which the exception was thrown. + + `pFrame` + [in] A pointer to an ICorDebugFrame object that represents a frame, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. + + `nOffset` + [in] An integer that specifies an offset, as determined by the `dwEventType` parameter. For more information, see the table in the Remarks section. + + `dwEventType` + [in] A value of the CorDebugExceptionCallbackType enumeration that specifies the type of this exception callback. + + `dwFlags` + [in] A value of the [CorDebugExceptionFlags](cordebugexceptionflags-enumeration.md) enumeration that specifies additional information about the exception + +## Remarks + + The `Exception` callback is called at various points during the search phase of the exception-handling process. That is, it can be called more than once while unwinding an exception. + + The exception being processed can be retrieved from the ICorDebugThread object referenced by the `pThread` parameter. + + The particular frame and offset are determined by the `dwEventType` parameter as follows: + +|Value of `dwEventType`|Value of `pFrame`|Value of `nOffset`| +|----------------------------|-----------------------|------------------------| +|DEBUG_EXCEPTION_FIRST_CHANCE|The frame that threw the exception.|The instruction pointer in the frame.| +|DEBUG_EXCEPTION_USER_FIRST_CHANCE|The user-code frame closest to the point of the thrown exception.|The instruction pointer in the frame.| +|DEBUG_EXCEPTION_CATCH_HANDLER_FOUND|The frame that contains the catch handler.|The common intermediate language (CIL) offset of the beginning of the catch handler.| +|DEBUG_EXCEPTION_UNHANDLED|NULL|Undefined.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorDebugManagedCallback2 Interface](icordebugmanagedcallback2-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md index 1df543530af88..642fa363c548b 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmanagedcallback2-functionremapopportunity-method.md @@ -2,70 +2,70 @@ description: "Learn more about: ICorDebugManagedCallback2::FunctionRemapOpportunity Method" title: "ICorDebugManagedCallback2::FunctionRemapOpportunity Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugManagedCallback2.FunctionRemapOpportunity" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugManagedCallback2::FunctionRemapOpportunity" -helpviewer_keywords: +helpviewer_keywords: - "FunctionRemapOpportunity method [.NET Framework debugging]" - "ICorDebugManagedCallback2::FunctionRemapOpportunity method [.NET Framework debugging]" ms.assetid: 0d6471bc-ad9b-4b1d-a307-c10443918863 -topic_type: +topic_type: - "apiref" --- # ICorDebugManagedCallback2::FunctionRemapOpportunity Method -Notifies the debugger that code execution has reached a sequence point in an older version of an edited function. - -## Syntax - -```cpp -HRESULT FunctionRemapOpportunity ( - [in] ICorDebugAppDomain *pAppDomain, - [in] ICorDebugThread *pThread, - [in] ICorDebugFunction *pOldFunction, - [in] ICorDebugFunction *pNewFunction, - [in] ULONG32 oldILOffset -); -``` - -## Parameters - - `pAppDomain` - [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the edited function. - - `pThread` - [in] A pointer to an ICorDebugThread object that represents the thread on which the remap breakpoint was encountered. - - `pOldFunction` - [in] A pointer to an ICorDebugFunction object that represents the version of the function that is currently running on the thread. - - `pNewFunction` - [in] A pointer to an ICorDebugFunction object that represents the latest version of the function. - - `oldILOffset` - [in] The Microsoft intermediate language (MSIL) offset of the instruction pointer in the old version of the function. - -## Remarks - - This callback gives the debugger an opportunity to remap the instruction pointer to its proper place in the new version of the specified function by calling the [ICorDebugILFrame2::RemapFunction](icordebugilframe2-remapfunction-method.md) method. If the debugger does not call `RemapFunction` before calling the [ICorDebugController::Continue](icordebugcontroller-continue-method.md) method, the runtime will continue to execute the old code and will fire another `FunctionRemapOpportunity` callback at the next sequence point. - - This callback will be invoked for every frame that is executing an older version of the given function until the debugger returns S_OK. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Notifies the debugger that code execution has reached a sequence point in an older version of an edited function. + +## Syntax + +```cpp +HRESULT FunctionRemapOpportunity ( + [in] ICorDebugAppDomain *pAppDomain, + [in] ICorDebugThread *pThread, + [in] ICorDebugFunction *pOldFunction, + [in] ICorDebugFunction *pNewFunction, + [in] ULONG32 oldILOffset +); +``` + +## Parameters + + `pAppDomain` + [in] A pointer to an ICorDebugAppDomain object that represents the application domain containing the edited function. + + `pThread` + [in] A pointer to an ICorDebugThread object that represents the thread on which the remap breakpoint was encountered. + + `pOldFunction` + [in] A pointer to an ICorDebugFunction object that represents the version of the function that is currently running on the thread. + + `pNewFunction` + [in] A pointer to an ICorDebugFunction object that represents the latest version of the function. + + `oldILOffset` + [in] The common intermediate language (CIL) offset of the instruction pointer in the old version of the function. + +## Remarks + + This callback gives the debugger an opportunity to remap the instruction pointer to its proper place in the new version of the specified function by calling the [ICorDebugILFrame2::RemapFunction](icordebugilframe2-remapfunction-method.md) method. If the debugger does not call `RemapFunction` before calling the [ICorDebugController::Continue](icordebugcontroller-continue-method.md) method, the runtime will continue to execute the old code and will fire another `FunctionRemapOpportunity` callback at the next sequence point. + + This callback will be invoked for every frame that is executing an older version of the given function until the debugger returns S_OK. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorDebugManagedCallback2 Interface](icordebugmanagedcallback2-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md b/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md index bbdbc7b522f88..372d1a0bbad23 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule-enablejitdebugging-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugModule::EnableJITDebugging Method" title: "ICorDebugModule::EnableJITDebugging Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule.EnableJITDebugging" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule::EnableJITDebugging" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugModule::EnableJITDebugging method [.NET Framework debugging]" - "EnableJITDebugging method [.NET Framework debugging]" ms.assetid: 0a65e2a4-5bb6-496c-ae6f-40474426b5a6 -topic_type: +topic_type: - "apiref" --- # ICorDebugModule::EnableJITDebugging Method -Controls whether the just-in-time (JIT) compiler preserves debugging information for methods within this module. - -## Syntax - -```cpp -HRESULT EnableJITDebugging( - [in] BOOL bTrackJITInfo, - [in] BOOL bAllowJitOpts -); -``` - -## Parameters - - `bTrackJITInfo` - [in] Set this value to `true` to enable the JIT compiler to preserve mapping information between the Microsoft intermediate language (MSIL) version and the JIT-compiled version of each method in this module. - - `bAllowJitOpts` - [in] Set this value to `true` to enable the JIT compiler to generate code with certain JIT-specific optimizations for debugging. - -## Remarks - - JIT debugging is enabled by default for all modules that are loaded when the debugger is active. Programmatically enabling or disabling the settings overrides global settings. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Controls whether the just-in-time (JIT) compiler preserves debugging information for methods within this module. + +## Syntax + +```cpp +HRESULT EnableJITDebugging( + [in] BOOL bTrackJITInfo, + [in] BOOL bAllowJitOpts +); +``` + +## Parameters + + `bTrackJITInfo` + [in] Set this value to `true` to enable the JIT compiler to preserve mapping information between the common intermediate language (CIL) version and the JIT-compiled version of each method in this module. + + `bAllowJitOpts` + [in] Set this value to `true` to enable the JIT compiler to generate code with certain JIT-specific optimizations for debugging. + +## Remarks + + JIT debugging is enabled by default for all modules that are loaded when the debugger is active. Programmatically enabling or disabling the settings overrides global settings. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md b/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md index 4d15be5d3f590..4a4cbc1bb269a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule-getfunctionfromtoken-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugModule::GetFunctionFromToken Method" title: "ICorDebugModule::GetFunctionFromToken Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule.GetFunctionFromToken" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule::GetFunctionFromToken" -helpviewer_keywords: +helpviewer_keywords: - "GetFunctionFromToken method, ICorDebugModule interface [.NET Framework debugging]" - "ICorDebugModule::GetFunctionFromToken method [.NET Framework debugging]" ms.assetid: 6fe12194-4ef7-43c1-9570-ade35ccf127a -topic_type: +topic_type: - "apiref" --- # ICorDebugModule::GetFunctionFromToken Method -Gets the function that is specified by the metadata token. - -## Syntax - -```cpp -HRESULT GetFunctionFromToken( - [in] mdMethodDef methodDef, - [out] ICorDebugFunction **ppFunction -); -``` - -## Parameters - - `methodDef` - [in] A `mdMethodDef` metadata token that references the function's metadata. - - `ppFunction` - [out] A pointer to the address of a ICorDebugFunction interface object that represents the function. - -## Remarks - - The `GetFunctionFromToken` method returns a CORDBG_E_FUNCTION_NOT_IL HRESULT if the value passed in `methodDef` does not refer to a Microsoft intermediate language (MSIL) method. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Gets the function that is specified by the metadata token. + +## Syntax + +```cpp +HRESULT GetFunctionFromToken( + [in] mdMethodDef methodDef, + [out] ICorDebugFunction **ppFunction +); +``` + +## Parameters + + `methodDef` + [in] A `mdMethodDef` metadata token that references the function's metadata. + + `ppFunction` + [out] A pointer to the address of a ICorDebugFunction interface object that represents the function. + +## Remarks + + The `GetFunctionFromToken` method returns a CORDBG_E_FUNCTION_NOT_IL HRESULT if the value passed in `methodDef` does not refer to a common intermediate language (CIL) method. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md b/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md index 67fa5b280e31e..91ab4017f4cb1 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule2-applychanges-method.md @@ -2,70 +2,70 @@ description: "Learn more about: ICorDebugModule2::ApplyChanges Method" title: "ICorDebugModule2::ApplyChanges Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule2.ApplyChanges" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule2::ApplyChanges" -helpviewer_keywords: +helpviewer_keywords: - "ApplyChanges method [.NET Framework debugging]" - "ICorDebugModule2::ApplyChanges method [.NET Framework debugging]" ms.assetid: 96fa3406-6a6f-41a1-88c6-d9bc5d1a16d1 -topic_type: +topic_type: - "apiref" --- # ICorDebugModule2::ApplyChanges Method -Applies the changes in the metadata and the changes in the Microsoft intermediate language (MSIL) code to the running process. - -## Syntax - -```cpp -HRESULT ApplyChanges ( - [in] ULONG cbMetadata, - [in, size_is(cbMetadata)] BYTE pbMetadata[], - [in] ULONG cbIL, - [in, size_is(cbIL)] BYTE pbIL[] -); -``` - -## Parameters - - `cbMetadata` - [in] Size, in bytes, of the delta metadata. - - `pbMetadata` - [in] Buffer that contains the delta metadata. The address of the buffer is returned from the [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md) method. - - The relative virtual addresses (RVAs) in the metadata should be relative to the start of the MSIL code. - - `cbIL` - [in] Size, in bytes, of the delta MSIL code. - - `pbIL` - [in] Buffer that contains the updated MSIL code. - -## Remarks - - The `pbMetadata` parameter is in a special delta metadata format (as output by [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md)). `pbMetadata` takes previous metadata as a base and describes individual changes to apply to that base. - - In contrast, the `pbIL[`] parameter contains the new MSIL for the updated method, and is meant to completely replace the previous MSIL for that method - - When the delta MSIL and the metadata have been created in the debugger’s memory, the debugger calls `ApplyChanges` to send the changes into the common language runtime (CLR). The runtime updates its metadata tables, places the new MSIL into the process, and sets up a just-in-time (JIT) compilation of the new MSIL. When the changes have been applied, the debugger should call [IMetaDataEmit2::ResetENCLog](../metadata/imetadataemit2-resetenclog-method.md) to prepare for the next editing session. The debugger may then continue the process. - - Whenever the debugger calls `ApplyChanges` on a module that has delta metadata, it should also call [IMetaDataEmit::ApplyEditAndContinue](../metadata/imetadataemit-applyeditandcontinue-method.md) with the same delta metadata on all of its copies of that module’s metadata except for the copy used to emit the changes. If a copy of the metadata somehow becomes out-of-sync with the actual metadata, the debugger can always throw away that copy and obtain a new copy. - - If the `ApplyChanges` method fails, the debug session is in an invalid state and must be restarted. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Applies the changes in the metadata and the changes in the common intermediate language (CIL) code to the running process. + +## Syntax + +```cpp +HRESULT ApplyChanges ( + [in] ULONG cbMetadata, + [in, size_is(cbMetadata)] BYTE pbMetadata[], + [in] ULONG cbIL, + [in, size_is(cbIL)] BYTE pbIL[] +); +``` + +## Parameters + + `cbMetadata` + [in] Size, in bytes, of the delta metadata. + + `pbMetadata` + [in] Buffer that contains the delta metadata. The address of the buffer is returned from the [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md) method. + + The relative virtual addresses (RVAs) in the metadata should be relative to the start of the CIL code. + + `cbIL` + [in] Size, in bytes, of the delta CIL code. + + `pbIL` + [in] Buffer that contains the updated CIL code. + +## Remarks + + The `pbMetadata` parameter is in a special delta metadata format (as output by [IMetaDataEmit2::SaveDeltaToMemory](../metadata/imetadataemit2-savedeltatomemory-method.md)). `pbMetadata` takes previous metadata as a base and describes individual changes to apply to that base. + + In contrast, the `pbIL[`] parameter contains the new CIL for the updated method, and is meant to completely replace the previous CIL for that method + + When the delta CIL and the metadata have been created in the debugger’s memory, the debugger calls `ApplyChanges` to send the changes into the common language runtime (CLR). The runtime updates its metadata tables, places the new CIL into the process, and sets up a just-in-time (JIT) compilation of the new CIL. When the changes have been applied, the debugger should call [IMetaDataEmit2::ResetENCLog](../metadata/imetadataemit2-resetenclog-method.md) to prepare for the next editing session. The debugger may then continue the process. + + Whenever the debugger calls `ApplyChanges` on a module that has delta metadata, it should also call [IMetaDataEmit::ApplyEditAndContinue](../metadata/imetadataemit-applyeditandcontinue-method.md) with the same delta metadata on all of its copies of that module’s metadata except for the copy used to emit the changes. If a copy of the metadata somehow becomes out-of-sync with the actual metadata, the debugger can always throw away that copy and obtain a new copy. + + If the `ApplyChanges` method fails, the debug session is in an invalid state and must be restarted. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md b/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md index caf3ba6faf4d1..6adf72f0e41aa 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugmodule2-interface.md @@ -2,49 +2,49 @@ description: "Learn more about: ICorDebugModule2 Interface" title: "ICorDebugModule2 Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugModule2" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugModule2" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugModule2 interface [.NET Framework debugging]" ms.assetid: 0847e64f-fdbe-4c96-8168-da20fdc84d80 -topic_type: +topic_type: - "apiref" --- # ICorDebugModule2 Interface -Serves as a logical extension to the ICorDebugModule interface. - -## Methods - -|Method|Description| -|------------|-----------------| -|[ApplyChanges Method](icordebugmodule2-applychanges-method.md)|Applies the changes in the metadata and the changes in the Microsoft intermediate language (MSIL) code to the running process.| -|[GetJITCompilerFlags Method](icordebugmodule2-getjitcompilerflags-method.md)|Gets the flags that control the just-in-time (JIT) compilation for this `ICorDebugModule2`.| -|[ResolveAssembly Method](icordebugmodule2-resolveassembly-method.md)|Resolves the assembly referenced by the specified metadata token.| -|[SetJITCompilerFlags Method](icordebugmodule2-setjitcompilerflags-method.md)|Sets the flags that control the JIT compilation for this `ICorDebugModule2`.| -|[SetJMCStatus Method](icordebugmodule2-setjmcstatus-method.md)|Sets the Just My Code (JMC) status of all methods of all the classes in this `ICorDebugModule2` to the specified value, except those in the `pTokens` array, which it sets to the opposite value.| - -## Remarks - +Serves as a logical extension to the ICorDebugModule interface. + +## Methods + +|Method|Description| +|------------|-----------------| +|[ApplyChanges Method](icordebugmodule2-applychanges-method.md)|Applies the changes in the metadata and the changes in the common intermediate language (CIL) code to the running process.| +|[GetJITCompilerFlags Method](icordebugmodule2-getjitcompilerflags-method.md)|Gets the flags that control the just-in-time (JIT) compilation for this `ICorDebugModule2`.| +|[ResolveAssembly Method](icordebugmodule2-resolveassembly-method.md)|Resolves the assembly referenced by the specified metadata token.| +|[SetJITCompilerFlags Method](icordebugmodule2-setjitcompilerflags-method.md)|Sets the flags that control the JIT compilation for this `ICorDebugModule2`.| +|[SetJMCStatus Method](icordebugmodule2-setjmcstatus-method.md)|Sets the Just My Code (JMC) status of all methods of all the classes in this `ICorDebugModule2` to the specified value, except those in the `pTokens` array, which it sets to the opposite value.| + +## Remarks + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md index d0e65756e4c23..43249b1e78706 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess-readmemory-method.md @@ -2,63 +2,63 @@ description: "Learn more about: ICorDebugProcess::ReadMemory Method" title: "ICorDebugProcess::ReadMemory Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugProcess.ReadMemory" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugProcess::ReadMemory" -helpviewer_keywords: +helpviewer_keywords: - "ReadMemory method [.NET Framework debugging]" - "ICorDebugProcess::ReadMemory method [.NET Framework debugging]" ms.assetid: 28e4b2f6-9589-445c-be24-24a3306795e7 -topic_type: +topic_type: - "apiref" --- # ICorDebugProcess::ReadMemory Method -Reads a specified area of memory for this process. - -## Syntax - -```cpp -HRESULT ReadMemory( +Reads a specified area of memory for this process. + +## Syntax + +```cpp +HRESULT ReadMemory( [in] CORDB_ADDRESS address, - [in] DWORD size, - [out, size_is(size), length_is(size)] BYTE buffer[], - [out] SIZE_T *read); -``` - -## Parameters - - `address` - [in] A `CORDB_ADDRESS` value that specifies the base address of the memory to be read. - - `size` - [in] The number of bytes to be read from memory. - - `buffer` - [out] A buffer that receives the contents of the memory. - - `read` - [out] A pointer to the number of bytes transferred into the specified buffer. - -## Remarks - - The `ReadMemory` method is primarily intended to be used by interop debugging to inspect memory regions that are being used by the unmanaged portion of the debuggee. This method can also be used to read Microsoft intermediate language (MSIL) code and native JIT-compiled code. - - Any managed breakpoints will be removed from the data that is returned in the `buffer` parameter. No adjustments will be made for native breakpoints set by [ICorDebugProcess2::SetUnmanagedBreakpoint](icordebugprocess2-setunmanagedbreakpoint-method.md). - - No caching of process memory is performed. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - + [in] DWORD size, + [out, size_is(size), length_is(size)] BYTE buffer[], + [out] SIZE_T *read); +``` + +## Parameters + + `address` + [in] A `CORDB_ADDRESS` value that specifies the base address of the memory to be read. + + `size` + [in] The number of bytes to be read from memory. + + `buffer` + [out] A buffer that receives the contents of the memory. + + `read` + [out] A pointer to the number of bytes transferred into the specified buffer. + +## Remarks + + The `ReadMemory` method is primarily intended to be used by interop debugging to inspect memory regions that are being used by the unmanaged portion of the debuggee. This method can also be used to read common intermediate language (CIL) code and native JIT-compiled code. + + Any managed breakpoints will be removed from the data that is returned in the `buffer` parameter. No adjustments will be made for native breakpoints set by [ICorDebugProcess2::SetUnmanagedBreakpoint](icordebugprocess2-setunmanagedbreakpoint-method.md). + + No caching of process memory is performed. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md b/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md index 8652479fc6ba7..64568884aaf8e 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugprocess2-setdesiredngencompilerflags-method.md @@ -2,56 +2,56 @@ description: "Learn more about: ICorDebugProcess2::SetDesiredNGENCompilerFlags Method" title: "ICorDebugProcess2::SetDesiredNGENCompilerFlags Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugProcess2.SetDesiredNGENCompilerFlags" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugProcess2::SetDesiredNGENCompilerFlags" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugProcess2::SetDesiredNGENCompilerFlags method [.NET Framework debugging]" - "SetDesiredNGENCompilerFlags method [.NET Framework debugging]" ms.assetid: 98320175-7c5e-4dbb-8683-86fa82e2641f -topic_type: +topic_type: - "apiref" --- # ICorDebugProcess2::SetDesiredNGENCompilerFlags Method -Sets the flags that must be embedded in a precompiled image in order for the runtime to load that image into the current process. - -## Syntax - -```cpp -HRESULT SetDesiredNGENCompilerFlags ( - [in] DWORD pdwFlags -); -``` - -## Parameters - - `pdwFlags` - [in] A value of the [CorDebugJITCompilerFlags](cordebugjitcompilerflags-enumeration.md) enumeration that specifies the compiler flags used to select the correct pre-compiled image. - -## Remarks - - The `SetDesiredNGENCompilerFlags` method specifies the flags that must be embedded in a precompiled image so that the runtime will load that image into this process. The flags set by this method are used only to select the correct precompiled image. If no such image exists, the runtime will load the Microsoft intermediate language (MSIL) image and the just-in-time (JIT) compiler instead. In that case, the debugger must still use the [ICorDebugModule2::SetJITCompilerFlags](icordebugmodule2-setjitcompilerflags-method.md) method to set the flags as desired for the JIT compilation. - - If an image is loaded, but some JIT compiling must take place for that image (which will be the case if the image contains generics), the compiler flags specified by the `SetDesiredNGENCompilerFlags` method will apply to the extra JIT compilation. - - The `SetDesiredNGENCompilerFlags` method must be called during the [ICorDebugManagedCallback::CreateProcess](icordebugmanagedcallback-createprocess-method.md) callback. Attempts to call the `SetDesiredNGENCompilerFlags` method afterwards will fail. Also, attempts to set flags that are either not defined in the `CorDebugJITCompilerFlags` enumeration or are not legal for the given process will fail. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Sets the flags that must be embedded in a precompiled image in order for the runtime to load that image into the current process. + +## Syntax + +```cpp +HRESULT SetDesiredNGENCompilerFlags ( + [in] DWORD pdwFlags +); +``` + +## Parameters + + `pdwFlags` + [in] A value of the [CorDebugJITCompilerFlags](cordebugjitcompilerflags-enumeration.md) enumeration that specifies the compiler flags used to select the correct pre-compiled image. + +## Remarks + + The `SetDesiredNGENCompilerFlags` method specifies the flags that must be embedded in a precompiled image so that the runtime will load that image into this process. The flags set by this method are used only to select the correct precompiled image. If no such image exists, the runtime will load the common intermediate language (CIL) image and the just-in-time (JIT) compiler instead. In that case, the debugger must still use the [ICorDebugModule2::SetJITCompilerFlags](icordebugmodule2-setjitcompilerflags-method.md) method to set the flags as desired for the JIT compilation. + + If an image is loaded, but some JIT compiling must take place for that image (which will be the case if the image contains generics), the compiler flags specified by the `SetDesiredNGENCompilerFlags` method will apply to the extra JIT compilation. + + The `SetDesiredNGENCompilerFlags` method must be called during the [ICorDebugManagedCallback::CreateProcess](icordebugmanagedcallback-createprocess-method.md) callback. Attempts to call the `SetDesiredNGENCompilerFlags` method afterwards will fail. Also, attempts to set flags that are either not defined in the `CorDebugJITCompilerFlags` enumeration or are not legal for the given process will fail. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorDebug Interface](icordebug-interface.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md index d71b2c69db957..88e9b8ac1f94f 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-interface.md @@ -2,64 +2,64 @@ description: "Learn more about: ICorDebugStepper Interface" title: "ICorDebugStepper Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugStepper interface [.NET Framework debugging]" ms.assetid: ed8364eb-f01b-46f6-b5e3-5dda9cae2dfe -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper Interface -Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. - -## Methods - -|Method|Description| -|------------|-----------------| -|[Deactivate Method](icordebugstepper-deactivate-method.md)|Causes this `ICorDebugStepper` to cancel the last step command it received.| -|[IsActive Method](icordebugstepper-isactive-method.md)|Gets a value that indicates whether this `ICorDebugStepper` is currently executing a step.| -|[SetInterceptMask Method](icordebugstepper-setinterceptmask-method.md)|Sets a CorDebugIntercept value that specifies the types of code that are stepped into.| -|[SetRangeIL Method](icordebugstepper-setrangeil-method.md)|Sets a value that indicates whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values relative to the native code or to Microsoft intermediate language (MSIL) code of the method that is being stepped through.| -|[SetUnmappedStopMask Method](icordebugstepper-setunmappedstopmask-method.md)|Sets a CorDebugUnmappedStop value that specifies the type of unmapped code in which execution will halt.| -|[Step Method](icordebugstepper-step-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and optionally, to continue single-stepping through functions that are called within the thread.| -|[StepOut Method](icordebugstepper-stepout-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to complete when the current frame returns control to the calling frame.| -|[StepRange Method](icordebugstepper-steprange-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges.| - -## Remarks - - The `ICorDebugStepper` interface serves the following purposes: - -- It acts as an identifier between a step command that is issued and the completion of that command. - -- It provides a central interface to encapsulate all the stepping that can be performed. - -- It provides a way to prematurely cancel a stepping operation. - - There can be more than one stepper per thread. For example, a breakpoint may be hit while stepping over a function, and the user may wish to start a new stepping operation inside that function. It is up to the debugger to determine how to handle this situation. The debugger may want to cancel the original stepping operation or nest the two operations. The `ICorDebugStepper` interface supports both choices. - - A stepper may migrate between threads if the common language runtime (CLR) makes a cross-threaded, marshalled call. - +Represents a step in code execution that is performed by a debugger, serves as an identifier between the issuance and completion of a command, and provides a way to cancel a step. + +## Methods + +|Method|Description| +|------------|-----------------| +|[Deactivate Method](icordebugstepper-deactivate-method.md)|Causes this `ICorDebugStepper` to cancel the last step command it received.| +|[IsActive Method](icordebugstepper-isactive-method.md)|Gets a value that indicates whether this `ICorDebugStepper` is currently executing a step.| +|[SetInterceptMask Method](icordebugstepper-setinterceptmask-method.md)|Sets a CorDebugIntercept value that specifies the types of code that are stepped into.| +|[SetRangeIL Method](icordebugstepper-setrangeil-method.md)|Sets a value that indicates whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values relative to the native code or to common intermediate language (CIL) code of the method that is being stepped through.| +|[SetUnmappedStopMask Method](icordebugstepper-setunmappedstopmask-method.md)|Sets a CorDebugUnmappedStop value that specifies the type of unmapped code in which execution will halt.| +|[Step Method](icordebugstepper-step-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and optionally, to continue single-stepping through functions that are called within the thread.| +|[StepOut Method](icordebugstepper-stepout-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to complete when the current frame returns control to the calling frame.| +|[StepRange Method](icordebugstepper-steprange-method.md)|Causes this `ICorDebugStepper` to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges.| + +## Remarks + + The `ICorDebugStepper` interface serves the following purposes: + +- It acts as an identifier between a step command that is issued and the completion of that command. + +- It provides a central interface to encapsulate all the stepping that can be performed. + +- It provides a way to prematurely cancel a stepping operation. + + There can be more than one stepper per thread. For example, a breakpoint may be hit while stepping over a function, and the user may wish to start a new stepping operation inside that function. It is up to the debugger to determine how to handle this situation. The debugger may want to cancel the original stepping operation or nest the two operations. The `ICorDebugStepper` interface supports both choices. + + A stepper may migrate between threads if the common language runtime (CLR) makes a cross-threaded, marshalled call. + > [!NOTE] -> This interface does not support being called remotely, either cross-machine or cross-process. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +> This interface does not support being called remotely, either cross-machine or cross-process. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Debugging Interfaces](debugging-interfaces.md) diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md index 4988d2b6b70b3..0050f0e2e9f7d 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-setrangeil-method.md @@ -2,44 +2,44 @@ description: "Learn more about: ICorDebugStepper::SetRangeIL Method" title: "ICorDebugStepper::SetRangeIL Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper.SetRangeIL" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper::SetRangeIL" -helpviewer_keywords: +helpviewer_keywords: - "SetRangeIL method [.NET Framework debugging]" - "ICorDebugStepper::SetRangeIL method [.NET Framework debugging]" ms.assetid: a20c95f0-6da7-4b41-b27f-584211cebb92 -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper::SetRangeIL Method -Sets a value that specifies whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values that are relative to the native code or relative to Microsoft intermediate language (MSIL) code of the method that is being stepped through. - -## Syntax - -```cpp -HRESULT SetRangeIL ( - [in] BOOL bIL -); -``` - -## Parameters - - `bIL` - [in] Set to `true` to specify that the ranges are relative to the MSIL code. Set to `false` to specify that the ranges are relative to the native code. The default value is `true`. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Sets a value that specifies whether calls to [ICorDebugStepper::StepRange](icordebugstepper-steprange-method.md) pass argument values that are relative to the native code or relative to common intermediate language (CIL) code of the method that is being stepped through. + +## Syntax + +```cpp +HRESULT SetRangeIL ( + [in] BOOL bIL +); +``` + +## Parameters + + `bIL` + [in] Set to `true` to specify that the ranges are relative to the CIL code. Set to `false` to specify that the ranges are relative to the native code. The default value is `true`. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md index f4ed3a6170c4a..b4f8d7089cb0a 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-setunmappedstopmask-method.md @@ -2,52 +2,52 @@ description: "Learn more about: ICorDebugStepper::SetUnmappedStopMask Method" title: "ICorDebugStepper::SetUnmappedStopMask Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper.SetUnmappedStopMask" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper::SetUnmappedStopMask" -helpviewer_keywords: +helpviewer_keywords: - "ICorDebugStepper::SetUnmappedStopMask method [.NET Framework debugging]" - "SetUnmappedStopMask method [.NET Framework debugging]" ms.assetid: b1211981-e90c-4e05-8def-fa18d85ad9ab -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper::SetUnmappedStopMask Method -Sets a value that specifies the type of unmapped code in which execution will halt. - -## Syntax - -```cpp -HRESULT SetUnmappedStopMask ( - [in] CorDebugUnmappedStop mask -); -``` - -## Parameters - - `mask` - [in] A value of the CorDebugUnmappedStop enumeration that specifies the type of unmapped code in which the debugger will halt execution. - - The default value is STOP_OTHER_UNMAPPED. The value STOP_UNMANAGED is only valid with interop debugging. - -## Remarks - - When the debugger finds a just-in-time (JIT) compilation that has no corresponding mapping to Microsoft intermediate language (MSIL), it halts execution if the flag specifying that type of unmapped code has been set; otherwise, stepping transparently continues. - - If the debugger doesn't use a stepper to enter a method, then it won't necessarily step over unmapped code. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Sets a value that specifies the type of unmapped code in which execution will halt. + +## Syntax + +```cpp +HRESULT SetUnmappedStopMask ( + [in] CorDebugUnmappedStop mask +); +``` + +## Parameters + + `mask` + [in] A value of the CorDebugUnmappedStop enumeration that specifies the type of unmapped code in which the debugger will halt execution. + + The default value is STOP_OTHER_UNMAPPED. The value STOP_UNMANAGED is only valid with interop debugging. + +## Remarks + + When the debugger finds a just-in-time (JIT) compilation that has no corresponding mapping to common intermediate language (CIL), it halts execution if the flag specifying that type of unmapped code has been set; otherwise, stepping transparently continues. + + If the debugger doesn't use a stepper to enter a method, then it won't necessarily step over unmapped code. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md b/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md index 034f8ec4dd508..bf5b5372eab87 100644 --- a/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md +++ b/docs/framework/unmanaged-api/debugging/icordebugstepper-steprange-method.md @@ -2,60 +2,60 @@ description: "Learn more about: ICorDebugStepper::StepRange Method" title: "ICorDebugStepper::StepRange Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorDebugStepper.StepRange" -api_location: +api_location: - "mscordbi.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorDebugStepper::StepRange" -helpviewer_keywords: +helpviewer_keywords: - "StepRange method [.NET Framework debugging]" - "ICorDebugStepper::StepRange method [.NET Framework debugging]" ms.assetid: b9776112-6e6d-4708-892a-8873db02e16f -topic_type: +topic_type: - "apiref" --- # ICorDebugStepper::StepRange Method -Causes this ICorDebugStepper to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges. - -## Syntax - -```cpp -HRESULT StepRange ( - [in] BOOL bStepIn, - [in, size_is(cRangeCount)] COR_DEBUG_STEP_RANGE ranges[], - [in] ULONG32 cRangeCount -); -``` - -## Parameters - - `bStepIn` - [in] Set to `true` to step into a function that is called within the thread. Set to `false` to step over the function. - - `ranges` - [in] An array of COR_DEBUG_STEP_RANGE structures, each of which specifies a range. - - `cRangeCount` - [in] The size of the `ranges` array. - -## Remarks - - The `StepRange` method works like the [ICorDebugStepper::Step](icordebugstepper-step-method.md) method, except that it does not complete until code outside the given range is reached. - - This can be more efficient than stepping one instruction at a time. Ranges are specified as a list of offset pairs from the start of the stepper's frame. - - Ranges are relative to the Microsoft intermediate language (MSIL) code of a method. Call [ICorDebugStepper::SetRangeIL](icordebugstepper-setrangeil-method.md) with `false` to make the ranges relative to the native code of a method. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorDebug.idl, CorDebug.h - - **Library:** CorGuids.lib - +Causes this ICorDebugStepper to single-step through its containing thread, and to return when it reaches code beyond the last of the specified ranges. + +## Syntax + +```cpp +HRESULT StepRange ( + [in] BOOL bStepIn, + [in, size_is(cRangeCount)] COR_DEBUG_STEP_RANGE ranges[], + [in] ULONG32 cRangeCount +); +``` + +## Parameters + + `bStepIn` + [in] Set to `true` to step into a function that is called within the thread. Set to `false` to step over the function. + + `ranges` + [in] An array of COR_DEBUG_STEP_RANGE structures, each of which specifies a range. + + `cRangeCount` + [in] The size of the `ranges` array. + +## Remarks + + The `StepRange` method works like the [ICorDebugStepper::Step](icordebugstepper-step-method.md) method, except that it does not complete until code outside the given range is reached. + + This can be more efficient than stepping one instruction at a time. Ranges are specified as a list of offset pairs from the start of the stepper's frame. + + Ranges are relative to the common intermediate language (CIL) code of a method. Call [ICorDebugStepper::SetRangeIL](icordebugstepper-setrangeil-method.md) with `false` to make the ranges relative to the native code of a method. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorDebug.idl, CorDebug.h + + **Library:** CorGuids.lib + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] diff --git a/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md b/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md index 2c2c80079f9cc..de1a498c4ff48 100644 --- a/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md +++ b/docs/framework/unmanaged-api/diagnostics/corsymaddrkind-enumeration.md @@ -2,61 +2,61 @@ description: "Learn more about: CorSymAddrKind Enumeration" title: "CorSymAddrKind Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "CorSymAddrKind" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "CorSymAddrKind" -helpviewer_keywords: +helpviewer_keywords: - "CorSymAddrKind enumeration [.NET Framework debugging]" ms.assetid: 3ef841c2-cade-42ee-ba34-2ef91d6d0879 -topic_type: +topic_type: - "apiref" --- # CorSymAddrKind Enumeration -Indicates the type of memory address. - -## Syntax - -```cpp -typedef enum CorSymAddrKind -{ - ADDR_IL_OFFSET = 1, - ADDR_NATIVE_RVA = 2, - ADDR_NATIVE_REGISTER = 3, - ADDR_NATIVE_REGREL = 4, - ADDR_NATIVE_OFFSET = 5, - ADDR_NATIVE_REGREG = 6, - ADDR_NATIVE_REGSTK = 7, - ADDR_NATIVE_STKREG = 8, - ADDR_BITFIELD = 9, - ADDR_NATIVE_ISECTOFFSET = 10 -} CorSymAddrKind; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`ADDR_IL_OFFSET`|Indicates a Microsoft intermediate language (MSIL) local variable or parameter index.| -|`ADDR_NATIVE_RVA`|Indicates a relative virtual address into a module.| -|`ADDR_NATIVE_REGISTER`|Indicates a CPU register.| -|`ADDR_NATIVE_REGREL`|Indicates that the first address is a register and the second address is an offset.| -|`ADDR_NATIVE_OFFSET`|Indicates an offset from a base address.| -|`ADDR_NATIVE_REGREG`|Indicates that the first address is the low portion of a register, and the second address is the high portion.| -|`ADDR_NATIVE_REGSTK`|Indicates that the first address is the low portion of a register, the second is the high portion, and the third is an offset.| -|`ADDR_NATIVE_STKREG`|Indicates that the first address is a register, the second is an offset, and the third is the high portion of the register.| -|`ADDR_BITFIELD`|Indicates that the first address is the start of a field and the second address is the field length.| -|`ADDR_NATIVE_ISECTOFFSET`|Indicates that the first address is the section and the second address is an offset.| - -## Requirements - - **Header:** CorSym.idl, CorSym.h - +Indicates the type of memory address. + +## Syntax + +```cpp +typedef enum CorSymAddrKind +{ + ADDR_IL_OFFSET = 1, + ADDR_NATIVE_RVA = 2, + ADDR_NATIVE_REGISTER = 3, + ADDR_NATIVE_REGREL = 4, + ADDR_NATIVE_OFFSET = 5, + ADDR_NATIVE_REGREG = 6, + ADDR_NATIVE_REGSTK = 7, + ADDR_NATIVE_STKREG = 8, + ADDR_BITFIELD = 9, + ADDR_NATIVE_ISECTOFFSET = 10 +} CorSymAddrKind; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`ADDR_IL_OFFSET`|Indicates a common intermediate language (CIL) local variable or parameter index.| +|`ADDR_NATIVE_RVA`|Indicates a relative virtual address into a module.| +|`ADDR_NATIVE_REGISTER`|Indicates a CPU register.| +|`ADDR_NATIVE_REGREL`|Indicates that the first address is a register and the second address is an offset.| +|`ADDR_NATIVE_OFFSET`|Indicates an offset from a base address.| +|`ADDR_NATIVE_REGREG`|Indicates that the first address is the low portion of a register, and the second address is the high portion.| +|`ADDR_NATIVE_REGSTK`|Indicates that the first address is the low portion of a register, the second is the high portion, and the third is an offset.| +|`ADDR_NATIVE_STKREG`|Indicates that the first address is a register, the second is an offset, and the third is the high portion of the register.| +|`ADDR_BITFIELD`|Indicates that the first address is the start of a field and the second address is the field length.| +|`ADDR_NATIVE_ISECTOFFSET`|Indicates that the first address is the section and the second address is an offset.| + +## Requirements + + **Header:** CorSym.idl, CorSym.h + ## See also - [Diagnostics Symbol Store Enumerations](diagnostics-symbol-store-enumerations.md) diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md index a8553a08ece93..e6e3d5b02af1e 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getranges-method.md @@ -2,66 +2,66 @@ description: "Learn more about: ISymUnmanagedMethod::GetRanges Method" title: "ISymUnmanagedMethod::GetRanges Method" ms.date: "03/30/2017" -api_name: +api_name: - "ISymUnmanagedMethod.GetRanges" -api_location: +api_location: - "diasymreader.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ISymUnmanagedMethod::GetRanges" -helpviewer_keywords: +helpviewer_keywords: - "ISymUnmanagedMethod::GetRanges method [.NET Framework debugging]" - "GetRanges method [.NET Framework debugging]" ms.assetid: a85283d8-379c-417a-9736-ddeeef9bcf50 -topic_type: +topic_type: - "apiref" --- # ISymUnmanagedMethod::GetRanges Method -Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of Microsoft intermediate language (MSIL) that the position covers within this method. The array is an array of integers and has the format [start, end, start, end]. The number of range pairs is the length of the array divided by 2. - -## Syntax - -```cpp -HRESULT GetRanges( - [in] ISymUnmanagedDocument* document, - [in] ULONG32 line, - [in] ULONG32 column, - [in] ULONG32 cRanges, - [out] ULONG32 *pcRanges, - [out, size_is(cRanges), - length_is(*pcRanges)] ULONG32 ranges[]); -``` - -## Parameters - - `document` - [in] The document for which the offset is requested. - - `line` - [in] The document line corresponding to the ranges. - - `column` - [in] The document column corresponding to the ranges. - - `cRanges` - [in] The size of the `ranges` array. - - `pcRanges` - [out] A pointer to a `ULONG32` that receives the size of the buffer required to contain the ranges. - - `ranges` - [out] A pointer to the buffer that receives the ranges. - -## Return Value - - S_OK if the method succeeds; otherwise, E_FAIL or some other error code. - -## Requirements - - **Header:** CorSym.idl, CorSym.h - +Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of common intermediate language (CIL) that the position covers within this method. The array is an array of integers and has the format [start, end, start, end]. The number of range pairs is the length of the array divided by 2. + +## Syntax + +```cpp +HRESULT GetRanges( + [in] ISymUnmanagedDocument* document, + [in] ULONG32 line, + [in] ULONG32 column, + [in] ULONG32 cRanges, + [out] ULONG32 *pcRanges, + [out, size_is(cRanges), + length_is(*pcRanges)] ULONG32 ranges[]); +``` + +## Parameters + + `document` + [in] The document for which the offset is requested. + + `line` + [in] The document line corresponding to the ranges. + + `column` + [in] The document column corresponding to the ranges. + + `cRanges` + [in] The size of the `ranges` array. + + `pcRanges` + [out] A pointer to a `ULONG32` that receives the size of the buffer required to contain the ranges. + + `ranges` + [out] A pointer to the buffer that receives the ranges. + +## Return Value + + S_OK if the method succeeds; otherwise, E_FAIL or some other error code. + +## Requirements + + **Header:** CorSym.idl, CorSym.h + ## See also - [ISymUnmanagedMethod Interface](isymunmanagedmethod-interface.md) diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md index 606546fdafc98..d992f160444bd 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-getsequencepoints-method.md @@ -2,73 +2,73 @@ description: "Learn more about: ISymUnmanagedMethod::GetSequencePoints Method" title: "ISymUnmanagedMethod::GetSequencePoints Method" ms.date: "03/30/2017" -api_name: +api_name: - "ISymUnmanagedMethod.GetSequencePoints" -api_location: +api_location: - "diasymreader.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ISymUnmanagedMethod::GetSequencePoints" -helpviewer_keywords: +helpviewer_keywords: - "ISymUnmanagedMethod::GetSequencePoints method [.NET Framework debugging]" - "GetSequencePoints method [.NET Framework debugging]" ms.assetid: f909ac48-3d8f-49fb-a369-e3d9959151cd -topic_type: +topic_type: - "apiref" --- # ISymUnmanagedMethod::GetSequencePoints Method -Gets all the sequence points within this method. - -## Syntax - -```cpp -HRESULT GetSequencePoints( - [in] ULONG32 cPoints, - [out] ULONG32 *pcPoints, - [in, size_is(cPoints)] ULONG32 offsets[], - [in, size_is(cPoints)] ISymUnmanagedDocument* documents[], - [in, size_is(cPoints)] ULONG32 lines[], - [in, size_is(cPoints)] ULONG32 columns[], - [in, size_is(cPoints)] ULONG32 endLines[], - [in, size_is(cPoints)] ULONG32 endColumns[]); -``` - -## Parameters - - `cPoints` - [in] A `ULONG32` that receives the size of the `offsets`, `documents`, `lines`, `columns`, `endLines`, and `endColumns` arrays. - - `pcPoints` - [out] A pointer to a `ULONG32` that receives the length of the buffer required to contain the sequence points. - - `offsets` - [in] An array in which to store the Microsoft intermediate language (MSIL) offsets from the beginning of the method for the sequence points. - - `documents` - [in] An array in which to store the documents in which the sequence points are located. - - `lines` - [in] An array in which to store the lines in the documents at which the sequence points are located. - - `columns` - [in] An array in which to store the columns in the documents at which the sequence points are located. - - `endLines` - [in] The array of lines in the documents at which the sequence points end. - - `endColumns` - [in] The array of columns in the documents at which the sequence points end. - -## Return Value - - S_OK if the method succeeds; otherwise, E_FAIL or some other error code. - -## Requirements - - **Header:** CorSym.idl, CorSym.h - +Gets all the sequence points within this method. + +## Syntax + +```cpp +HRESULT GetSequencePoints( + [in] ULONG32 cPoints, + [out] ULONG32 *pcPoints, + [in, size_is(cPoints)] ULONG32 offsets[], + [in, size_is(cPoints)] ISymUnmanagedDocument* documents[], + [in, size_is(cPoints)] ULONG32 lines[], + [in, size_is(cPoints)] ULONG32 columns[], + [in, size_is(cPoints)] ULONG32 endLines[], + [in, size_is(cPoints)] ULONG32 endColumns[]); +``` + +## Parameters + + `cPoints` + [in] A `ULONG32` that receives the size of the `offsets`, `documents`, `lines`, `columns`, `endLines`, and `endColumns` arrays. + + `pcPoints` + [out] A pointer to a `ULONG32` that receives the length of the buffer required to contain the sequence points. + + `offsets` + [in] An array in which to store the common intermediate language (CIL) offsets from the beginning of the method for the sequence points. + + `documents` + [in] An array in which to store the documents in which the sequence points are located. + + `lines` + [in] An array in which to store the lines in the documents at which the sequence points are located. + + `columns` + [in] An array in which to store the columns in the documents at which the sequence points are located. + + `endLines` + [in] The array of lines in the documents at which the sequence points end. + + `endColumns` + [in] The array of columns in the documents at which the sequence points end. + +## Return Value + + S_OK if the method succeeds; otherwise, E_FAIL or some other error code. + +## Requirements + + **Header:** CorSym.idl, CorSym.h + ## See also - [ISymUnmanagedMethod Interface](isymunmanagedmethod-interface.md) diff --git a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md index 5d525925a1027..1ff575cf0e7aa 100644 --- a/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md +++ b/docs/framework/unmanaged-api/diagnostics/isymunmanagedmethod-interface.md @@ -2,43 +2,43 @@ description: "Learn more about: ISymUnmanagedMethod Interface" title: "ISymUnmanagedMethod Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ISymUnmanagedMethod" -api_location: +api_location: - "diasymreader.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ISymUnmanagedMethod" -helpviewer_keywords: +helpviewer_keywords: - "ISymUnmanagedMethod interface [.NET Framework debugging]" ms.assetid: f204d74c-cc79-4092-83bb-60654be95649 -topic_type: +topic_type: - "apiref" --- # ISymUnmanagedMethod Interface -Represents a method within the symbol store. This interface provides access to only the symbol-related attributes of a method, instead of the type-related attributes. - -## Methods - -|Method|Description| -|------------|-----------------| -|[GetNamespace Method](isymunmanagedmethod-getnamespace-method.md)|Gets the namespace within which this method is defined.| -|[GetOffset Method](isymunmanagedmethod-getoffset-method.md)|Returns the offset within this method that corresponds to a given position within a document.| -|[GetParameters Method](isymunmanagedmethod-getparameters-method.md)|Gets the parameters for this method.| -|[GetRanges Method](isymunmanagedmethod-getranges-method.md)|Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of Microsoft intermediate language (MSIL) that the position covers within this method.| -|[GetRootScope Method](isymunmanagedmethod-getrootscope-method.md)|Gets the root lexical scope within this method. This scope encloses the entire method.| -|[GetScopeFromOffset Method](isymunmanagedmethod-getscopefromoffset-method.md)|Gets the most enclosing lexical scope within this method that encloses the given offset.| -|[GetSequencePointCount Method](isymunmanagedmethod-getsequencepointcount-method.md)|Gets the count of sequence points within this method.| -|[GetSequencePoints Method](isymunmanagedmethod-getsequencepoints-method.md)|Gets all the sequence points within this method.| -|[GetSourceStartEnd Method](isymunmanagedmethod-getsourcestartend-method.md)|Gets the start and end document positions for the source of this method.| -|[GetToken Method](isymunmanagedmethod-gettoken-method.md)|Returns the metadata token for this method.| - -## Requirements +Represents a method within the symbol store. This interface provides access to only the symbol-related attributes of a method, instead of the type-related attributes. + +## Methods + +|Method|Description| +|------------|-----------------| +|[GetNamespace Method](isymunmanagedmethod-getnamespace-method.md)|Gets the namespace within which this method is defined.| +|[GetOffset Method](isymunmanagedmethod-getoffset-method.md)|Returns the offset within this method that corresponds to a given position within a document.| +|[GetParameters Method](isymunmanagedmethod-getparameters-method.md)|Gets the parameters for this method.| +|[GetRanges Method](isymunmanagedmethod-getranges-method.md)|Given a position in a document, returns an array of start and end offset pairs that correspond to the ranges of common intermediate language (CIL) that the position covers within this method.| +|[GetRootScope Method](isymunmanagedmethod-getrootscope-method.md)|Gets the root lexical scope within this method. This scope encloses the entire method.| +|[GetScopeFromOffset Method](isymunmanagedmethod-getscopefromoffset-method.md)|Gets the most enclosing lexical scope within this method that encloses the given offset.| +|[GetSequencePointCount Method](isymunmanagedmethod-getsequencepointcount-method.md)|Gets the count of sequence points within this method.| +|[GetSequencePoints Method](isymunmanagedmethod-getsequencepoints-method.md)|Gets all the sequence points within this method.| +|[GetSourceStartEnd Method](isymunmanagedmethod-getsourcestartend-method.md)|Gets the start and end document positions for the source of this method.| +|[GetToken Method](isymunmanagedmethod-gettoken-method.md)|Returns the metadata token for this method.| + +## Requirements + + **Header:** CorSym.idl, CorSym.h - **Header:** CorSym.idl, CorSym.h - ## See also - [Diagnostics Symbol Store Interfaces](diagnostics-symbol-store-interfaces.md) diff --git a/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md b/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md index 39e58fa96b27a..423f93c02a248 100644 --- a/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrprobingassemblyenum-get-method.md @@ -2,75 +2,75 @@ description: "Learn more about: ICLRProbingAssemblyEnum::Get Method" title: "ICLRProbingAssemblyEnum::Get Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICLRProbingAssemblyEnum.Get" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICLRProbingAssemblyEnum::Get" -helpviewer_keywords: +helpviewer_keywords: - "Get method, ICLRProbingAssemblyEnum interface [.NET Framework hosting]" - "ICLRProbingAssemblyEnum::Get method [.NET Framework hosting]" ms.assetid: fdb67a77-782f-44cf-a8a1-b75999b0f3c8 -topic_type: +topic_type: - "apiref" --- # ICLRProbingAssemblyEnum::Get Method -Gets the assembly identity at the specified index. - -## Syntax - -```cpp -HRESULT Get ( - [in] DWORD dwIndex, - [out, size_is(*pcchBufferSize)] LPWSTR pwzBuffer, - [in, out] DWORD *pcchBufferSize -); -``` - -## Parameters - - `dwIndex` - [in] The zero-based index of the assembly identity to return. - - `pwzBuffer` - [out] A buffer containing the assembly identity data. - - `pcchBufferSize` - [in, out] The size of the `pwzBuffer` buffer. - -## Return Value - -|HRESULT|Description| -|-------------|-----------------| -|S_OK|`Get` returned successfully.| -|ERROR_INSUFFICIENT_BUFFER|`pwzBuffer` is too small.| -|ERROR_NO_MORE_ITEMS|The enumeration contains no more items.| -|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| -|HOST_E_TIMEOUT|The call timed out.| -|HOST_E_NOT_OWNER|The caller does not own the lock.| -|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| -|E_FAIL|An unknown catastrophic failure occurred. If a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to any hosting methods return HOST_E_CLRNOTAVAILABLE.| - -## Remarks - - The identity at index 0 is the identity specific to the processor architecture. The identity at index 1 is the architecture-neutral assembly for Microsoft intermediate language (MSIL). The identity at index 2 contains no architecture information. - - `Get` is typically called twice. The first call supplies a null value for `pwzBuffer`, and sets `pcchBufferSize` to the size appropriate for `pwzBuffer`. The second call supplies an appropriately sized `pwzBuffer`, and contains the canonical assembly identity data upon completion. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** MSCorEE.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets the assembly identity at the specified index. + +## Syntax + +```cpp +HRESULT Get ( + [in] DWORD dwIndex, + [out, size_is(*pcchBufferSize)] LPWSTR pwzBuffer, + [in, out] DWORD *pcchBufferSize +); +``` + +## Parameters + + `dwIndex` + [in] The zero-based index of the assembly identity to return. + + `pwzBuffer` + [out] A buffer containing the assembly identity data. + + `pcchBufferSize` + [in, out] The size of the `pwzBuffer` buffer. + +## Return Value + +|HRESULT|Description| +|-------------|-----------------| +|S_OK|`Get` returned successfully.| +|ERROR_INSUFFICIENT_BUFFER|`pwzBuffer` is too small.| +|ERROR_NO_MORE_ITEMS|The enumeration contains no more items.| +|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| +|HOST_E_TIMEOUT|The call timed out.| +|HOST_E_NOT_OWNER|The caller does not own the lock.| +|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| +|E_FAIL|An unknown catastrophic failure occurred. If a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to any hosting methods return HOST_E_CLRNOTAVAILABLE.| + +## Remarks + + The identity at index 0 is the identity specific to the processor architecture. The identity at index 1 is the architecture-neutral assembly for common intermediate language (CIL). The identity at index 2 contains no architecture information. + + `Get` is typically called twice. The first call supplies a null value for `pwzBuffer`, and sets `pcchBufferSize` to the size appropriate for `pwzBuffer`. The second call supplies an appropriately sized `pwzBuffer`, and contains the canonical assembly identity data upon completion. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** MSCorEE.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRProbingAssemblyEnum Interface](iclrprobingassemblyenum-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md b/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md index a799a184bfd9d..3caf8c9b0279a 100644 --- a/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md +++ b/docs/framework/unmanaged-api/hosting/iclrvalidator-interface.md @@ -2,41 +2,41 @@ description: "Learn more about: ICLRValidator Interface" title: "ICLRValidator Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICLRValidator" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICLRValidator" -helpviewer_keywords: +helpviewer_keywords: - "ICLRValidator interface [.NET Framework hosting]" ms.assetid: 2edd0a10-77fb-4173-91eb-f2970cc364d0 -topic_type: +topic_type: - "apiref" --- # ICLRValidator Interface -Provides methods for validating portable executable (PE) images and reporting validation errors. - -## Methods - -|Method|Description| -|------------|-----------------| -|[FormatEventInfo Method](iclrvalidator-formateventinfo-method.md)|Gets a detailed message about the specified validation error.| -|[Validate Method](iclrvalidator-validate-method.md)|Validates the portable executable or Microsoft intermediate language (MSIL) in the specified file.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Provides methods for validating portable executable (PE) images and reporting validation errors. + +## Methods + +|Method|Description| +|------------|-----------------| +|[FormatEventInfo Method](iclrvalidator-formateventinfo-method.md)|Gets a detailed message about the specified validation error.| +|[Validate Method](iclrvalidator-validate-method.md)|Validates the portable executable or common intermediate language (CIL) in the specified file.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRErrorReportingManager Interface](iclrerrorreportingmanager-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md b/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md index 5b1fa3ead2c39..0ac6dd1afc64b 100644 --- a/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md +++ b/docs/framework/unmanaged-api/hosting/iclrvalidator-validate-method.md @@ -2,87 +2,87 @@ description: "Learn more about: ICLRValidator::Validate Method" title: "ICLRValidator::Validate Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICLRValidator.Validate" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICLRValidator::Validate" -helpviewer_keywords: +helpviewer_keywords: - "Validate method, ICLRValidator interface [.NET Framework hosting]" - "ICLRValidator::Validate method [.NET Framework hosting]" ms.assetid: 0b1b432a-d234-4002-839b-81366c3a8bdc -topic_type: +topic_type: - "apiref" --- # ICLRValidator::Validate Method -Validates the portable executable (PE) or Microsoft intermediate language (MSIL) in the specified file. - -## Syntax - -```cpp -HRESULT Validate ( - [in] IVEHandler *veh, - [in] unsigned long ulAppDomainId, - [in] unsigned long ulFlags, - [in] unsigned long ulMaxError, - [in] unsigned long token, - [in] LPWSTR fileName, - [in, size_is(ulSize)] BYTE *pe, - [in] unsigned long ulSize +Validates the portable executable (PE) or common intermediate language (CIL) in the specified file. + +## Syntax + +```cpp +HRESULT Validate ( + [in] IVEHandler *veh, + [in] unsigned long ulAppDomainId, + [in] unsigned long ulFlags, + [in] unsigned long ulMaxError, + [in] unsigned long token, + [in] LPWSTR fileName, + [in, size_is(ulSize)] BYTE *pe, + [in] unsigned long ulSize ); -``` - -## Parameters - - `veh` - [in] A pointer to an `IVEHandler` instance that handles validation errors. - - `ulAppDomainId` - [in] The identifier for the current . - - `ulFlags` - [in] A combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the kind of validation that should be performed. - - `ulMaxError` - [in] The maximum number of errors to allow before exiting the validation. - - `token` - [in] Unused. - - `fileName` - [in] The name of the file to be validated. - - `pe` - [in] A pointer to the file buffer. - - `ulSize` - [in] The size, in bytes, of the file to be validated. - -## Return Value - -|HRESULT|Description| -|-------------|-----------------| -|S_OK|`Validate` returned successfully.| -|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| -|HOST_E_TIMEOUT|The call timed out.| -|HOST_E_NOT_OWNER|The caller does not own the lock.| -|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| -|E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +``` + +## Parameters + + `veh` + [in] A pointer to an `IVEHandler` instance that handles validation errors. + + `ulAppDomainId` + [in] The identifier for the current . + + `ulFlags` + [in] A combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the kind of validation that should be performed. + + `ulMaxError` + [in] The maximum number of errors to allow before exiting the validation. + + `token` + [in] Unused. + + `fileName` + [in] The name of the file to be validated. + + `pe` + [in] A pointer to the file buffer. + + `ulSize` + [in] The size, in bytes, of the file to be validated. + +## Return Value + +|HRESULT|Description| +|-------------|-----------------| +|S_OK|`Validate` returned successfully.| +|HOST_E_CLRNOTAVAILABLE|The common language runtime (CLR) has not been loaded into a process, or the CLR is in a state in which it cannot run managed code or process the call successfully.| +|HOST_E_TIMEOUT|The call timed out.| +|HOST_E_NOT_OWNER|The caller does not own the lock.| +|HOST_E_ABANDONED|An event was canceled while a blocked thread or fiber was waiting on it.| +|E_FAIL|An unknown catastrophic failure occurred. When a method returns E_FAIL, the CLR is no longer usable within the process. Subsequent calls to hosting methods return HOST_E_CLRNOTAVAILABLE.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRValidator Interface](iclrvalidator-interface.md) diff --git a/docs/framework/unmanaged-api/hosting/ivalidator-interface.md b/docs/framework/unmanaged-api/hosting/ivalidator-interface.md index 1f1d55cc9a195..07404ee94ddd6 100644 --- a/docs/framework/unmanaged-api/hosting/ivalidator-interface.md +++ b/docs/framework/unmanaged-api/hosting/ivalidator-interface.md @@ -2,41 +2,41 @@ description: "Learn more about: IValidator Interface" title: "IValidator Interface" ms.date: "03/30/2017" -api_name: +api_name: - "IValidator" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "IValidator" -helpviewer_keywords: +helpviewer_keywords: - "IValidator interface [.NET Framework hosting]" ms.assetid: b297e3b0-20f9-478f-b707-5e2eecb2b5b2 -topic_type: +topic_type: - "apiref" --- # IValidator Interface -Provides methods for validating portable executable (PE) images and reporting validation errors. - -## Methods - -|Method|Description| -|------------|-----------------| -|Validate|Validates the specified PE or Microsoft intermediate language (MSIL) file.| -|FormatEventInfo|Gets the error message corresponding to the specified validation error.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Provides methods for validating portable executable (PE) images and reporting validation errors. + +## Methods + +|Method|Description| +|------------|-----------------| +|Validate|Validates the specified PE or common intermediate language (CIL) file.| +|FormatEventInfo|Gets the error message corresponding to the specified validation error.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Hosting Interfaces](hosting-interfaces.md) diff --git a/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md b/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md index 866bb4eb3d30e..f98a917cdb9c9 100644 --- a/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md +++ b/docs/framework/unmanaged-api/hosting/ivalidator-validate-method.md @@ -2,72 +2,72 @@ description: "Learn more about: IValidator::Validate Method" title: "IValidator::Validate Method" ms.date: "03/30/2017" -api_name: +api_name: - "IValidator.Validate" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "Validate" -helpviewer_keywords: +helpviewer_keywords: - "IValidator::Validate method [.NET Framework hosting]" - "Validate method, IValidator interface [.NET Framework hosting]" ms.assetid: 7d68666a-fb73-4455-bebd-908d49a16abc -topic_type: +topic_type: - "apiref" --- # IValidator::Validate Method -Validates the specified portable executable (PE) or Microsoft intermediate language (MSIL) file. - -## Syntax - -```cpp -HRESULT Validate ( - [in] IVEHandler *veh, - [in] IUnknown *pAppDomain, - [in] unsigned long ulFlags, - [in] unsigned long ulMaxError, - [in] unsigned long token, - [in] LPWSTR fileName, - [in, size_is(ulSize)] BYTE *pe, - [in] unsigned long ulSize -); -``` - -## Parameters - - `veh` - [in] A pointer to an `IVEHandler` instance that handles validation errors. - - `pAppDomain` - [in] A pointer to the application domain in which the file is loaded. - - `ulFlags` - [in] A bitwise combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the validations that should be performed. - - `ulMaxError` - [in] The maximum number of errors to allow before exiting the validation. - - `token` - [in] Not used. - - `fileName` - [in] A string that specifies the name of the file to be validated. - - `pe` - [in] A pointer to the memory buffer in which the file is stored. - - `ulSize` - [in] The size, in bytes, of the file to be validated. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** Included as a resource in MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] +Validates the specified portable executable (PE) or common intermediate language (CIL) file. + +## Syntax + +```cpp +HRESULT Validate ( + [in] IVEHandler *veh, + [in] IUnknown *pAppDomain, + [in] unsigned long ulFlags, + [in] unsigned long ulMaxError, + [in] unsigned long token, + [in] LPWSTR fileName, + [in, size_is(ulSize)] BYTE *pe, + [in] unsigned long ulSize +); +``` + +## Parameters + + `veh` + [in] A pointer to an `IVEHandler` instance that handles validation errors. + + `pAppDomain` + [in] A pointer to the application domain in which the file is loaded. + + `ulFlags` + [in] A bitwise combination of [ValidatorFlags](validatorflags-enumeration.md) values, indicating the validations that should be performed. + + `ulMaxError` + [in] The maximum number of errors to allow before exiting the validation. + + `token` + [in] Not used. + + `fileName` + [in] A string that specifies the name of the file to be validated. + + `pe` + [in] A pointer to the memory buffer in which the file is stored. + + `ulSize` + [in] The size, in bytes, of the file to be validated. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** Included as a resource in MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] diff --git a/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md b/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md index 77c3f7f79436c..581dc0f4e5841 100644 --- a/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md +++ b/docs/framework/unmanaged-api/hosting/validatorflags-enumeration.md @@ -2,56 +2,56 @@ description: "Learn more about: ValidatorFlags Enumeration" title: "ValidatorFlags Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "ValidatorFlags" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ValidatorFlags" -helpviewer_keywords: +helpviewer_keywords: - "ValidatorFlags enumeration [.NET Framework hosting]" ms.assetid: a3f5c266-3fcc-4ad1-aaf5-4cdbe26304ad -topic_type: +topic_type: - "apiref" --- # ValidatorFlags Enumeration -Contains values that indicate the type of validation that should be performed in a call to the [ICLRValidator::Validate](iclrvalidator-validate-method.md) method. - -## Syntax - -```cpp -enum ValidatorFlags { - VALIDATOR_EXTRA_VERBOSE = 0x00000001, - VALIDATOR_SHOW_SOURCE_LINES = 0x00000002, - VALIDATOR_CHECK_ILONLY = 0x00000004, - VALIDATOR_CHECK_PEFORMAT_ONLY = 0x00000008, - VALIDATOR_NOCHECK_PEFORMAT = 0x00000010, -}; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`VALIDATOR_CHECK_ILONLY`|Specifies that only the Microsoft intermediate language (MSIL) in the executable file should be validated.| -|`VALIDATOR_CHECK_PEFORMAT_ONLY`|Specifies that only the format of the executable file should be validated.| -|`VALIDATOR_EXTRA_VERBOSE`|Specifies that all types of validation should be performed and reported on.| -|`VALIDATOR_NOCHECK_PEFORMAT`|Specifies that the format of the executable file should not be validated.| -|`VALIDATOR_SHOW_SOURCE_LINES`|Specifies that validation error messages should include the lines of source code that raise validation errors. This field value is not valid in .NET Framework version 2.0.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** IValidator.idl, IValidator.h - - **Library:** MSCorEE.dll - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Contains values that indicate the type of validation that should be performed in a call to the [ICLRValidator::Validate](iclrvalidator-validate-method.md) method. + +## Syntax + +```cpp +enum ValidatorFlags { + VALIDATOR_EXTRA_VERBOSE = 0x00000001, + VALIDATOR_SHOW_SOURCE_LINES = 0x00000002, + VALIDATOR_CHECK_ILONLY = 0x00000004, + VALIDATOR_CHECK_PEFORMAT_ONLY = 0x00000008, + VALIDATOR_NOCHECK_PEFORMAT = 0x00000010, +}; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`VALIDATOR_CHECK_ILONLY`|Specifies that only the common intermediate language (CIL) in the executable file should be validated.| +|`VALIDATOR_CHECK_PEFORMAT_ONLY`|Specifies that only the format of the executable file should be validated.| +|`VALIDATOR_EXTRA_VERBOSE`|Specifies that all types of validation should be performed and reported on.| +|`VALIDATOR_NOCHECK_PEFORMAT`|Specifies that the format of the executable file should not be validated.| +|`VALIDATOR_SHOW_SOURCE_LINES`|Specifies that validation error messages should include the lines of source code that raise validation errors. This field value is not valid in .NET Framework version 2.0.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** IValidator.idl, IValidator.h + + **Library:** MSCorEE.dll + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICLRErrorReportingManager Interface](iclrerrorreportingmanager-interface.md) diff --git a/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md b/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md index 58dec4d774f1c..f487cd450ac27 100644 --- a/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md +++ b/docs/framework/unmanaged-api/metadata/cormethodimpl-enumeration.md @@ -2,81 +2,81 @@ description: "Learn more about: CorMethodImpl Enumeration" title: "CorMethodImpl Enumeration" ms.date: "03/30/2017" -api_name: +api_name: - "CorMethodImpl" -api_location: +api_location: - "mscoree.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "CorMethodImpl" -helpviewer_keywords: +helpviewer_keywords: - "CorMethodImpl enumeration [.NET Framework metadata]" ms.assetid: ffbb3caf-20da-4a4b-8983-77376e72b990 -topic_type: +topic_type: - "apiref" --- # CorMethodImpl Enumeration -Contains values that describe method implementation features. - -## Syntax - -```cpp -typedef enum CorMethodImpl { - - miCodeTypeMask = 0x0003, - miIL = 0x0000, - miNative = 0x0001, - miOPTIL = 0x0002, - miRuntime = 0x0003, - - miManagedMask = 0x0004, - miUnmanaged = 0x0004, - miManaged = 0x0000, - - miForwardRef = 0x0010, - miPreserveSig = 0x0080, - - miInternalCall = 0x1000, - miSynchronized = 0x0020, - miNoInlining = 0x0008, - miAggressiveInlining = 0x0100, - miNoOptimization = 0x0040, - miMaxMethodImplVal = 0xffff - -} CorMethodImpl; -``` - -## Members - -|Member|Description| -|------------|-----------------| -|`miCodeTypeMask`|Flags that describe code type.| -|`miIL`|Specifies that the method implementation is Microsoft intermediate language (MSIL).| -|`miNative`|Specifies that the method implementation is native.| -|`miOPTIL`|Specifies that the method implementation is OPTIL.| -|`miRuntime`|Specifies that the method implementation is provided by the common language runtime.| -|`miManagedMask`|Flags that indicate whether the code is managed or unmanaged.| -|`miUnmanaged`|Specifies that the method implementation is unmanaged.| -|`miManaged`|Specifies that the method implementation is managed.| -|`miForwardRef`|Specifies that the method is defined. This flag is used primarily in merge scenarios.| -|`miPreserveSig`|Specifies that the method signature cannot be mangled for an HRESULT conversion.| -|`miInternalCall`|Reserved for internal use by the common language runtime.| -|`miSynchronized`|Specifies that the method is single-threaded through its body.| -|`miNoInlining`|Specifies that the method cannot be inlined.| -|`miAggressiveInlining`|Specifies that the method should be inlined if possible.| -|`miNoOptimization`|Specifies that the method should not be optimized.| -|`miMaxMethodImplVal`|The maximum valid value for a `CorMethodImpl`.| - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorHdr.h - - **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] - +Contains values that describe method implementation features. + +## Syntax + +```cpp +typedef enum CorMethodImpl { + + miCodeTypeMask = 0x0003, + miIL = 0x0000, + miNative = 0x0001, + miOPTIL = 0x0002, + miRuntime = 0x0003, + + miManagedMask = 0x0004, + miUnmanaged = 0x0004, + miManaged = 0x0000, + + miForwardRef = 0x0010, + miPreserveSig = 0x0080, + + miInternalCall = 0x1000, + miSynchronized = 0x0020, + miNoInlining = 0x0008, + miAggressiveInlining = 0x0100, + miNoOptimization = 0x0040, + miMaxMethodImplVal = 0xffff + +} CorMethodImpl; +``` + +## Members + +|Member|Description| +|------------|-----------------| +|`miCodeTypeMask`|Flags that describe code type.| +|`miIL`|Specifies that the method implementation is common intermediate language (CIL).| +|`miNative`|Specifies that the method implementation is native.| +|`miOPTIL`|Specifies that the method implementation is OPTIL.| +|`miRuntime`|Specifies that the method implementation is provided by the common language runtime.| +|`miManagedMask`|Flags that indicate whether the code is managed or unmanaged.| +|`miUnmanaged`|Specifies that the method implementation is unmanaged.| +|`miManaged`|Specifies that the method implementation is managed.| +|`miForwardRef`|Specifies that the method is defined. This flag is used primarily in merge scenarios.| +|`miPreserveSig`|Specifies that the method signature cannot be mangled for an HRESULT conversion.| +|`miInternalCall`|Reserved for internal use by the common language runtime.| +|`miSynchronized`|Specifies that the method is single-threaded through its body.| +|`miNoInlining`|Specifies that the method cannot be inlined.| +|`miAggressiveInlining`|Specifies that the method should be inlined if possible.| +|`miNoOptimization`|Specifies that the method should not be optimized.| +|`miMaxMethodImplVal`|The maximum valid value for a `CorMethodImpl`.| + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorHdr.h + + **.NET Framework Versions:** [!INCLUDE[net_current_v10plus](../../../../includes/net-current-v10plus-md.md)] + ## See also - [Metadata Enumerations](metadata-enumerations.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md b/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md index 31865933f695c..01aeafe799197 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilercallback-jitcompilationstarted-method.md @@ -2,59 +2,59 @@ description: "Learn more about: ICorProfilerCallback::JITCompilationStarted Method" title: "ICorProfilerCallback::JITCompilationStarted Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerCallback.JITCompilationStarted" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerCallback::JITCompilationStarted" -helpviewer_keywords: +helpviewer_keywords: - "JITCompilationStarted method [.NET Framework profiling]" - "ICorProfilerCallback::JITCompilationStarted method [.NET Framework profiling]" ms.assetid: 31782b36-d311-4518-8f45-25f65385af5b -topic_type: +topic_type: - "apiref" --- # ICorProfilerCallback::JITCompilationStarted Method -Notifies the profiler that the just-in-time (JIT) compiler has started to compile a function. - -## Syntax - -```cpp -HRESULT JITCompilationStarted( - [in] FunctionID functionId, - [in] BOOL fIsSafeToBlock); -``` - -## Parameters - - `functionId` - [in] The ID of the function for which the compilation is starting. - - `fIsSafeToBlock` - [in] A value indicating to the profiler whether blocking will affect the operation of the runtime. The value is `true` if blocking may cause the runtime to wait for the calling thread to return from this callback; otherwise, `false`. - - Although a value of `true` will not harm the runtime, it can skew the profiling results. - -## Remarks - - It is possible to receive more than one pair of `JITCompilationStarted` and [ICorProfilerCallback::JITCompilationFinished](icorprofilercallback-jitcompilationfinished-method.md) calls for each function because of the way the runtime handles class constructors. For example, the runtime starts to JIT-compile method A, but the class constructor for class B needs to be run. Therefore, the runtime JIT-compiles the constructor for class B and runs it. While the constructor is running, it makes a call to method A, which causes method A to be JIT-compiled again. In this scenario, the first JIT compilation of method A is halted. However, both attempts to JIT-compile method A are reported with JIT-compilation events. If the profiler is going to replace Microsoft intermediate language (MSIL) code for method A by calling the [ICorProfilerInfo::SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method, it must do so for both `JITCompilationStarted` events, but it may use the same MSIL block for both. - - Profilers must support the sequence of JIT callbacks in cases where two threads are simultaneously making callbacks. For example, thread A calls `JITCompilationStarted`. However, before thread A calls `JITCompilationFinished`, thread B calls [ICorProfilerCallback::ExceptionSearchFunctionEnter](icorprofilercallback-exceptionsearchfunctionenter-method.md) with the function ID from thread A's `JITCompilationStarted` callback. It might appear that the function ID should not yet be valid because a call to `JITCompilationFinished` had not yet been received by the profiler. However, in a case like this one, the function ID is valid. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Notifies the profiler that the just-in-time (JIT) compiler has started to compile a function. + +## Syntax + +```cpp +HRESULT JITCompilationStarted( + [in] FunctionID functionId, + [in] BOOL fIsSafeToBlock); +``` + +## Parameters + + `functionId` + [in] The ID of the function for which the compilation is starting. + + `fIsSafeToBlock` + [in] A value indicating to the profiler whether blocking will affect the operation of the runtime. The value is `true` if blocking may cause the runtime to wait for the calling thread to return from this callback; otherwise, `false`. + + Although a value of `true` will not harm the runtime, it can skew the profiling results. + +## Remarks + + It is possible to receive more than one pair of `JITCompilationStarted` and [ICorProfilerCallback::JITCompilationFinished](icorprofilercallback-jitcompilationfinished-method.md) calls for each function because of the way the runtime handles class constructors. For example, the runtime starts to JIT-compile method A, but the class constructor for class B needs to be run. Therefore, the runtime JIT-compiles the constructor for class B and runs it. While the constructor is running, it makes a call to method A, which causes method A to be JIT-compiled again. In this scenario, the first JIT compilation of method A is halted. However, both attempts to JIT-compile method A are reported with JIT-compilation events. If the profiler is going to replace common intermediate language (CIL) code for method A by calling the [ICorProfilerInfo::SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method, it must do so for both `JITCompilationStarted` events, but it may use the same CIL block for both. + + Profilers must support the sequence of JIT callbacks in cases where two threads are simultaneously making callbacks. For example, thread A calls `JITCompilationStarted`. However, before thread A calls `JITCompilationFinished`, thread B calls [ICorProfilerCallback::ExceptionSearchFunctionEnter](icorprofilercallback-exceptionsearchfunctionenter-method.md) with the function ID from thread A's `JITCompilationStarted` callback. It might appear that the function ID should not yet be valid because a call to `JITCompilationFinished` had not yet been received by the profiler. However, in a case like this one, the function ID is valid. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerCallback Interface](icorprofilercallback-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md index 7eb2b0548e21b..6e5c31af7edbb 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbody-method.md @@ -2,65 +2,65 @@ description: "Learn more about: ICorProfilerInfo::GetILFunctionBody Method" title: "ICorProfilerInfo::GetILFunctionBody Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo.GetILFunctionBody" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo::GetILFunctionBody" -helpviewer_keywords: +helpviewer_keywords: - "GetILFunctionBody method [.NET Framework profiling]" - "ICorProfilerInfo::GetILFunctionBody method [.NET Framework profiling]" ms.assetid: e29b46bc-5fdc-4894-b0c2-619df4b65ded -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo::GetILFunctionBody Method -Gets a pointer to the body of a method in Microsoft intermediate language (MSIL) code, starting at its header. - -## Syntax - -```cpp -HRESULT GetILFunctionBody( - [in] ModuleID moduleId, - [in] mdMethodDef methodId, - [out] LPCBYTE *ppMethodHeader, - [out] ULONG *pcbMethodSize); -``` - -## Parameters - - `moduleId` - [in] The ID of the module in which the function resides. - - `methodId` - [in] The metadata token for the method. - - `ppMethodHeader` - [out] A pointer to the method's header. - - `pcbMethodSize` - [out] An integer that specifies the size of the method. - -## Remarks - - A method is scoped by the module in which it lives. Because the `GetILFunctionBody` method is designed to give a tool access to the MSIL code before it has been loaded by the common language runtime (CLR), it uses the metadata token of the method to find the desired instance. - - `GetILFunctionBody` can return a CORPROF_E_FUNCTION_NOT_IL HRESULT if the `methodId` points to a method without any MSIL code (such as an abstract method, or a platform invoke (PInvoke) method). - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets a pointer to the body of a method in common intermediate language (CIL) code, starting at its header. + +## Syntax + +```cpp +HRESULT GetILFunctionBody( + [in] ModuleID moduleId, + [in] mdMethodDef methodId, + [out] LPCBYTE *ppMethodHeader, + [out] ULONG *pcbMethodSize); +``` + +## Parameters + + `moduleId` + [in] The ID of the module in which the function resides. + + `methodId` + [in] The metadata token for the method. + + `ppMethodHeader` + [out] A pointer to the method's header. + + `pcbMethodSize` + [out] An integer that specifies the size of the method. + +## Remarks + + A method is scoped by the module in which it lives. Because the `GetILFunctionBody` method is designed to give a tool access to the CIL code before it has been loaded by the common language runtime (CLR), it uses the metadata token of the method to find the desired instance. + + `GetILFunctionBody` can return a CORPROF_E_FUNCTION_NOT_IL HRESULT if the `methodId` points to a method without any CIL code (such as an abstract method, or a platform invoke (PInvoke) method). + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerInfo Interface](icorprofilerinfo-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md index c893db23593a2..1026889ea52bc 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getilfunctionbodyallocator-method.md @@ -2,55 +2,55 @@ description: "Learn more about: ICorProfilerInfo::GetILFunctionBodyAllocator Method" title: "ICorProfilerInfo::GetILFunctionBodyAllocator Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo.GetILFunctionBodyAllocator" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo::GetILFunctionBodyAllocator" -helpviewer_keywords: +helpviewer_keywords: - "GetILFunctionBodyAllocator method [.NET Framework profiling]" - "ICorProfilerInfo::GetILFunctionBodyAllocator method [.NET Framework profiling]" ms.assetid: 5da1bf3d-dddf-4892-b266-578ee54d570b -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo::GetILFunctionBodyAllocator Method -Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in Microsoft intermediate language (MSIL) code. - -## Syntax - -```cpp -HRESULT GetILFunctionBodyAllocator( - [in] ModuleID moduleId, - [out] IMethodMalloc **ppMalloc); -``` - -## Parameters - - `moduleId` - [in] The ID of the module in which the method resides. - - `ppMalloc` - [out] A pointer to an [IMethodMalloc](imethodmalloc-interface.md) interface that provides a method to allocate the memory. - -## Remarks - - A method body in MSIL code must be located as a relative virtual address (RVA), relative to the loaded module, which means that it follows the module within 4 GB. To make it easier for a tool to swap out the body of a method, the `GetILFunctionBodyAllocator` method ensures that memory is allocated within that range. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in common intermediate language (CIL) code. + +## Syntax + +```cpp +HRESULT GetILFunctionBodyAllocator( + [in] ModuleID moduleId, + [out] IMethodMalloc **ppMalloc); +``` + +## Parameters + + `moduleId` + [in] The ID of the module in which the method resides. + + `ppMalloc` + [out] A pointer to an [IMethodMalloc](imethodmalloc-interface.md) interface that provides a method to allocate the memory. + +## Remarks + + A method body in CIL code must be located as a relative virtual address (RVA), relative to the loaded module, which means that it follows the module within 4 GB. To make it easier for a tool to swap out the body of a method, the `GetILFunctionBodyAllocator` method ensures that memory is allocated within that range. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerInfo Interface](icorprofilerinfo-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md index 9850bef327436..4959b3ec491da 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-getiltonativemapping-method.md @@ -2,68 +2,68 @@ description: "Learn more about: ICorProfilerInfo::GetILToNativeMapping Method" title: "ICorProfilerInfo::GetILToNativeMapping Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo.GetILToNativeMapping" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo::GetILToNativeMapping" -helpviewer_keywords: +helpviewer_keywords: - "GetILToNativeMapping method, ICorProfilerInfo interface [.NET Framework profiling]" - "ICorProfilerInfo::GetILToNativeMapping method [.NET Framework profiling]" ms.assetid: 6a5431ef-22fb-4e53-bac5-703986297eb1 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo::GetILToNativeMapping Method -Gets a map from Microsoft intermediate language (MSIL) offsets to native offsets for the code contained in the specified function. - -## Syntax - -```cpp -HRESULT GetILToNativeMapping( - [in] FunctionID functionId, - [in] ULONG32 cMap, - [out] ULONG32 *pcMap, - [out, size_is(cMap), length_is(*pcMap)] - COR_DEBUG_IL_TO_NATIVE_MAP map[]); -``` - -## Parameters - - `functionId` - [in] The ID of the function that contains the code. - - `cMap` - [in] The maximum size of the `map` array. - - `pcMap` - [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. - - `map` - [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. - -## Remarks - - The `GetILToNativeMapping` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. - - After `GetILToNativeMapping` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping` again. - - Alternatively, you can first call `GetILToNativeMapping` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping` again. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets a map from common intermediate language (CIL) offsets to native offsets for the code contained in the specified function. + +## Syntax + +```cpp +HRESULT GetILToNativeMapping( + [in] FunctionID functionId, + [in] ULONG32 cMap, + [out] ULONG32 *pcMap, + [out, size_is(cMap), length_is(*pcMap)] + COR_DEBUG_IL_TO_NATIVE_MAP map[]); +``` + +## Parameters + + `functionId` + [in] The ID of the function that contains the code. + + `cMap` + [in] The maximum size of the `map` array. + + `pcMap` + [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. + + `map` + [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. + +## Remarks + + The `GetILToNativeMapping` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. + + After `GetILToNativeMapping` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping` again. + + Alternatively, you can first call `GetILToNativeMapping` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping` again. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [ICorProfilerInfo Interface](icorprofilerinfo-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md index 423dd4f3d6288..1d6e6e726cb19 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-interface.md @@ -2,83 +2,83 @@ description: "Learn more about: ICorProfilerInfo Interface" title: "ICorProfilerInfo Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo interface [.NET Framework profiling]" ms.assetid: eb4e4ce0-06e7-4469-bbc4-edc2eb5da4b1 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo Interface -Provides methods for use by code profilers to communicate with the common language runtime (CLR) to control event monitoring and request information. - +Provides methods for use by code profilers to communicate with the common language runtime (CLR) to control event monitoring and request information. + > [!NOTE] -> Each method in the `ICorProfilerInfo` interface returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. - -## Methods - -|Method|Description| -|------------|-----------------| -|[BeginInprocDebugging Method](icorprofilerinfo-begininprocdebugging-method.md)|Initializes in-process debugging support. This method is obsolete in .NET Framework version 2.0.| -|[EndInprocDebugging Method](icorprofilerinfo-endinprocdebugging-method.md)|Shuts down an in-process debugging session. This method is obsolete in .NET Framework version 2.0.| -|[ForceGC Method](icorprofilerinfo-forcegc-method.md)|Forces garbage collection to occur within the runtime.| -|[GetAppDomainInfo Method](icorprofilerinfo-getappdomaininfo-method.md)|Gets information about the specified application domain.| -|[GetAssemblyInfo Method](icorprofilerinfo-getassemblyinfo-method.md)|Gets information about the specified assembly.| -|[GetClassFromObject Method](icorprofilerinfo-getclassfromobject-method.md)|Gets the `ClassID` of an

object, given its `ObjectID`.| -|[GetClassFromToken Method](icorprofilerinfo-getclassfromtoken-method.md)|Gets the ID of the class, given the metadata token. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetClassFromTokenAndTypeArgs](icorprofilerinfo2-getclassfromtokenandtypeargs-method.md) method instead.| -|[GetClassIDInfo Method](icorprofilerinfo-getclassidinfo-method.md)|Gets the parent module and the metadata token for the specified class.| -|[GetCodeInfo Method](icorprofilerinfo-getcodeinfo-method.md)|Gets the extent of native code associated with the specified function ID. This method is obsolete. Use the [ICorProfilerInfo2::GetCodeInfo2](icorprofilerinfo2-getcodeinfo2-method.md) method instead.| -|[GetCurrentThreadID Method](icorprofilerinfo-getcurrentthreadid-method.md)|Gets the ID of the current thread, if it is a managed thread.| -|[GetEventMask Method](icorprofilerinfo-geteventmask-method.md)|Gets the current event categories for which the profiler wants to receive event notifications from the CLR.| -|[GetFunctionFromIP Method](icorprofilerinfo-getfunctionfromip-method.md)|Maps a managed code instruction pointer to a `FunctionID`.| -|[GetFunctionFromToken Method](icorprofilerinfo-getfunctionfromtoken-method.md)|Gets the ID of a function. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetFunctionFromTokenAndTypeArgs](icorprofilerinfo2-getfunctionfromtokenandtypeargs-method.md) method instead.| -|[GetFunctionInfo Method](icorprofilerinfo-getfunctioninfo-method.md)|Gets the parent class and metadata token for the specified function.| -|[GetHandleFromThread Method](icorprofilerinfo-gethandlefromthread-method.md)|Maps the ID of a thread to a Win32 thread handle.| -|[GetILFunctionBody Method](icorprofilerinfo-getilfunctionbody-method.md)|Gets a pointer to the body of a method in Microsoft intermediate language (MSIL) code, starting at its header.| -|[GetILFunctionBodyAllocator Method](icorprofilerinfo-getilfunctionbodyallocator-method.md)|Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in MSIL code.| -|[GetILToNativeMapping Method](icorprofilerinfo-getiltonativemapping-method.md)|Gets a map from MSIL offsets to native offsets for the code contained in the specified function.| -|[GetInprocInspectionInterface Method](icorprofilerinfo-getinprocinspectioninterface-method.md)|Gets an object that can be queried for an ICorDebugProcess interface. This method is obsolete in .NET Framework version 2.0.| -|[GetInprocInspectionIThisThread Method](icorprofilerinfo-getinprocinspectionithisthread-method.md)|Gets an object that can be queried for the ICorDebugThread interface. This method is obsolete in .NET Framework version 2.0.| -|[GetModuleInfo Method](icorprofilerinfo-getmoduleinfo-method.md)|Given a module ID, returns the file name of the module and the ID of the module's parent assembly.| -|[GetModuleMetaData Method](icorprofilerinfo-getmodulemetadata-method.md)|Gets a metadata interface instance that maps to the specified module.| -|[GetObjectSize Method](icorprofilerinfo-getobjectsize-method.md)|Gets the size of a specified object.| -|[GetThreadContext Method](icorprofilerinfo-getthreadcontext-method.md)|Gets the context identity currently associated with the specified thread.| -|[GetThreadInfo Method](icorprofilerinfo-getthreadinfo-method.md)|Gets the current Win32 thread identity for the specified thread.| -|[GetTokenAndMetadataFromFunction Method](icorprofilerinfo-gettokenandmetadatafromfunction-method.md)|Gets the metadata token and an instance of the metadata interface that can be used against the token for the specified function.| -|[IsArrayClass Method](icorprofilerinfo-isarrayclass-method.md)|Determines whether the specified class is an array class.| -|[SetEnterLeaveFunctionHooks Method](icorprofilerinfo-setenterleavefunctionhooks-method.md)|Specifies profiler-implemented functions to be called on "enter", "leave", and "tailcall" hooks of managed functions.| -|[SetEventMask Method](icorprofilerinfo-seteventmask-method.md)|Sets a value that specifies the types of events for which the profiler wants to receive notification from the CLR.| -|[SetFunctionIDMapper Method](icorprofilerinfo-setfunctionidmapper-method.md)|Specifies the profiler-implemented function that will be called to map `FunctionID` values to alternative values, which are passed to the profiler's function entry/exit hooks.| -|[SetFunctionReJIT Method](icorprofilerinfo-setfunctionrejit-method.md)|Not implemented. Do not use.| -|[SetILFunctionBody Method](icorprofilerinfo-setilfunctionbody-method.md)|Replaces the body of the specified function in the specified module.| -|[SetILInstrumentedCodeMap Method](icorprofilerinfo-setilinstrumentedcodemap-method.md)|Specifies how the offsets of a specified function's original MSIL map to the new offsets of the function's profiler-modified MSIL.| - -## Remarks +> Each method in the `ICorProfilerInfo` interface returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. + +## Methods + +|Method|Description| +|------------|-----------------| +|[BeginInprocDebugging Method](icorprofilerinfo-begininprocdebugging-method.md)|Initializes in-process debugging support. This method is obsolete in .NET Framework version 2.0.| +|[EndInprocDebugging Method](icorprofilerinfo-endinprocdebugging-method.md)|Shuts down an in-process debugging session. This method is obsolete in .NET Framework version 2.0.| +|[ForceGC Method](icorprofilerinfo-forcegc-method.md)|Forces garbage collection to occur within the runtime.| +|[GetAppDomainInfo Method](icorprofilerinfo-getappdomaininfo-method.md)|Gets information about the specified application domain.| +|[GetAssemblyInfo Method](icorprofilerinfo-getassemblyinfo-method.md)|Gets information about the specified assembly.| +|[GetClassFromObject Method](icorprofilerinfo-getclassfromobject-method.md)|Gets the `ClassID` of an

object, given its `ObjectID`.| +|[GetClassFromToken Method](icorprofilerinfo-getclassfromtoken-method.md)|Gets the ID of the class, given the metadata token. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetClassFromTokenAndTypeArgs](icorprofilerinfo2-getclassfromtokenandtypeargs-method.md) method instead.| +|[GetClassIDInfo Method](icorprofilerinfo-getclassidinfo-method.md)|Gets the parent module and the metadata token for the specified class.| +|[GetCodeInfo Method](icorprofilerinfo-getcodeinfo-method.md)|Gets the extent of native code associated with the specified function ID. This method is obsolete. Use the [ICorProfilerInfo2::GetCodeInfo2](icorprofilerinfo2-getcodeinfo2-method.md) method instead.| +|[GetCurrentThreadID Method](icorprofilerinfo-getcurrentthreadid-method.md)|Gets the ID of the current thread, if it is a managed thread.| +|[GetEventMask Method](icorprofilerinfo-geteventmask-method.md)|Gets the current event categories for which the profiler wants to receive event notifications from the CLR.| +|[GetFunctionFromIP Method](icorprofilerinfo-getfunctionfromip-method.md)|Maps a managed code instruction pointer to a `FunctionID`.| +|[GetFunctionFromToken Method](icorprofilerinfo-getfunctionfromtoken-method.md)|Gets the ID of a function. This method is obsolete in .NET Framework version 2.0. Use the [ICorProfilerInfo2::GetFunctionFromTokenAndTypeArgs](icorprofilerinfo2-getfunctionfromtokenandtypeargs-method.md) method instead.| +|[GetFunctionInfo Method](icorprofilerinfo-getfunctioninfo-method.md)|Gets the parent class and metadata token for the specified function.| +|[GetHandleFromThread Method](icorprofilerinfo-gethandlefromthread-method.md)|Maps the ID of a thread to a Win32 thread handle.| +|[GetILFunctionBody Method](icorprofilerinfo-getilfunctionbody-method.md)|Gets a pointer to the body of a method in common intermediate language (CIL) code, starting at its header.| +|[GetILFunctionBodyAllocator Method](icorprofilerinfo-getilfunctionbodyallocator-method.md)|Gets an interface that provides a method to allocate memory to be used for swapping out the body of a method in CIL code.| +|[GetILToNativeMapping Method](icorprofilerinfo-getiltonativemapping-method.md)|Gets a map from CIL offsets to native offsets for the code contained in the specified function.| +|[GetInprocInspectionInterface Method](icorprofilerinfo-getinprocinspectioninterface-method.md)|Gets an object that can be queried for an ICorDebugProcess interface. This method is obsolete in .NET Framework version 2.0.| +|[GetInprocInspectionIThisThread Method](icorprofilerinfo-getinprocinspectionithisthread-method.md)|Gets an object that can be queried for the ICorDebugThread interface. This method is obsolete in .NET Framework version 2.0.| +|[GetModuleInfo Method](icorprofilerinfo-getmoduleinfo-method.md)|Given a module ID, returns the file name of the module and the ID of the module's parent assembly.| +|[GetModuleMetaData Method](icorprofilerinfo-getmodulemetadata-method.md)|Gets a metadata interface instance that maps to the specified module.| +|[GetObjectSize Method](icorprofilerinfo-getobjectsize-method.md)|Gets the size of a specified object.| +|[GetThreadContext Method](icorprofilerinfo-getthreadcontext-method.md)|Gets the context identity currently associated with the specified thread.| +|[GetThreadInfo Method](icorprofilerinfo-getthreadinfo-method.md)|Gets the current Win32 thread identity for the specified thread.| +|[GetTokenAndMetadataFromFunction Method](icorprofilerinfo-gettokenandmetadatafromfunction-method.md)|Gets the metadata token and an instance of the metadata interface that can be used against the token for the specified function.| +|[IsArrayClass Method](icorprofilerinfo-isarrayclass-method.md)|Determines whether the specified class is an array class.| +|[SetEnterLeaveFunctionHooks Method](icorprofilerinfo-setenterleavefunctionhooks-method.md)|Specifies profiler-implemented functions to be called on "enter", "leave", and "tailcall" hooks of managed functions.| +|[SetEventMask Method](icorprofilerinfo-seteventmask-method.md)|Sets a value that specifies the types of events for which the profiler wants to receive notification from the CLR.| +|[SetFunctionIDMapper Method](icorprofilerinfo-setfunctionidmapper-method.md)|Specifies the profiler-implemented function that will be called to map `FunctionID` values to alternative values, which are passed to the profiler's function entry/exit hooks.| +|[SetFunctionReJIT Method](icorprofilerinfo-setfunctionrejit-method.md)|Not implemented. Do not use.| +|[SetILFunctionBody Method](icorprofilerinfo-setilfunctionbody-method.md)|Replaces the body of the specified function in the specified module.| +|[SetILInstrumentedCodeMap Method](icorprofilerinfo-setilinstrumentedcodemap-method.md)|Specifies how the offsets of a specified function's original CIL map to the new offsets of the function's profiler-modified CIL.| + +## Remarks + + A profiler calls a method in the `ICorProfilerInfo` interface to communicate with the CLR to control event monitoring and request information. + + The methods of the `ICorProfilerInfo` interface are implemented by the CLR using the free-threaded model. Each method returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. + + The CLR passes, via the profiler's implementation of [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md), an `ICorProfilerInfo` interface to each code profiler during initialization. A code profiler can then call methods of the `ICorProfilerInfo` interface to get information about managed code being executed under the control of the CLR. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib - A profiler calls a method in the `ICorProfilerInfo` interface to communicate with the CLR to control event monitoring and request information. - - The methods of the `ICorProfilerInfo` interface are implemented by the CLR using the free-threaded model. Each method returns an HRESULT to indicate success or failure. See CorError.h for a list of possible return codes. - - The CLR passes, via the profiler's implementation of [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md), an `ICorProfilerInfo` interface to each code profiler during initialization. A code profiler can then call methods of the `ICorProfilerInfo` interface to get information about managed code being executed under the control of the CLR. - -## Requirements + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - ## See also - [Profiling Interfaces](profiling-interfaces.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md index 6e9b3c3997f83..c397a9ed8e786 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo-setilinstrumentedcodemap-method.md @@ -19,7 +19,7 @@ topic_type: --- # ICorProfilerInfo::SetILInstrumentedCodeMap Method -Sets a code map for the specified function using the specified Microsoft intermediate language (MSIL) map entries. +Sets a code map for the specified function using the specified common intermediate language (CIL) map entries. > [!NOTE] > In .NET Framework version 2.0, calling `SetILInstrumentedCodeMap` on a `FunctionID` that represents a generic function in a particular application domain will affect all instances of that function in the application domain. @@ -46,17 +46,17 @@ HRESULT SetILInstrumentedCodeMap( [in] The number of elements in the `cILMapEntries` array. `rgILMapEntries`\ -[in] An array of COR_IL_MAP structures, each of which specifies an MSIL offset. +[in] An array of COR_IL_MAP structures, each of which specifies a CIL offset. ## Remarks -A profiler often inserts statements within the source code of a method in order to instrument that method (for example, to notify when a given source line is reached). `SetILInstrumentedCodeMap` enables a profiler to map the original MSIL instructions to their new locations. A profiler can use the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method to get the original MSIL offset for a given native offset. +A profiler often inserts statements within the source code of a method in order to instrument that method (for example, to notify when a given source line is reached). `SetILInstrumentedCodeMap` enables a profiler to map the original CIL instructions to their new locations. A profiler can use the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method to get the original CIL offset for a given native offset. -The debugger will assume that each old offset refers to an MSIL offset within the original, unmodified MSIL code, and that each new offset refers to the MSIL offset within the new, instrumented code. The map should be sorted in increasing order. For stepping to work properly, follow these guidelines: +The debugger will assume that each old offset refers to a CIL offset within the original, unmodified CIL code, and that each new offset refers to the CIL offset within the new, instrumented code. The map should be sorted in increasing order. For stepping to work properly, follow these guidelines: -- Do not reorder instrumented MSIL code. +- Do not reorder instrumented CIL code. -- Do not remove the original MSIL code. +- Do not remove the original CIL code. - Include entries for all the sequence points from the program database (PDB) file in the map. The map does not interpolate missing entries. So, given the following map: diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md index d719e39b0ed4a..d174477449488 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo2-getcodeinfo2-method.md @@ -2,68 +2,68 @@ description: "Learn more about: ICorProfilerInfo2::GetCodeInfo2 Method" title: "ICorProfilerInfo2::GetCodeInfo2 Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo2.GetCodeInfo2" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo2::GetCodeInfo2" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo2::GetCodeInfo2 method [.NET Framework profiling]" - "GetCodeInfo2 method [.NET Framework profiling]" ms.assetid: 532da6ee-7f0a-401b-a61e-fc47ec235d2e -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo2::GetCodeInfo2 Method -Gets the extents of native code associated with the specified `FunctionID`. - -## Syntax - -```cpp -HRESULT GetCodeInfo2( - [in] FunctionID functionID, - [in] ULONG32 cCodeInfos, - [out] ULONG32 *pcCodeInfos, - [out, size_is(cCodeInfos), length_is(*pcCodeInfos)] - COR_PRF_CODE_INFO codeInfos[]); -``` - -## Parameters - - `functionID` - [in] The ID of the function with which the native code is associated. - - `cCodeInfos` - [in] The size of the `codeInfos` array. - - `pcCodeInfos` - [out] A pointer to the total number of [COR_PRF_CODE_INFO](cor-prf-code-info-structure.md) structures available. - - `codeInfos` - [out] A caller-provided buffer. After the method returns, it contains an array of `COR_PRF_CODE_INFO` structures, each of which describes a block of native code. - -## Remarks - - The extents are sorted in order of increasing Microsoft intermediate language (MSIL) offset. - - After `GetCodeInfo2` returns, you must verify that the `codeInfos` buffer was large enough to contain all the `COR_PRF_CODE_INFO` structures. To do this, compare the value of `cCodeInfos` with the value of the `cchName` parameter. If `cCodeInfos` divided by the size of a `COR_PRF_CODE_INFO` structure is smaller than `pcCodeInfos`, allocate a larger `codeInfos` buffer, update `cCodeInfos` with the new, larger size, and call `GetCodeInfo2` again. - - Alternatively, you can first call `GetCodeInfo2` with a zero-length `codeInfos` buffer to obtain the correct buffer size. You can then set the `codeInfos` buffer size to the value returned in `pcCodeInfos`, multiplied by the size of a `COR_PRF_CODE_INFO` structure, and call `GetCodeInfo2` again. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +Gets the extents of native code associated with the specified `FunctionID`. + +## Syntax + +```cpp +HRESULT GetCodeInfo2( + [in] FunctionID functionID, + [in] ULONG32 cCodeInfos, + [out] ULONG32 *pcCodeInfos, + [out, size_is(cCodeInfos), length_is(*pcCodeInfos)] + COR_PRF_CODE_INFO codeInfos[]); +``` + +## Parameters + + `functionID` + [in] The ID of the function with which the native code is associated. + + `cCodeInfos` + [in] The size of the `codeInfos` array. + + `pcCodeInfos` + [out] A pointer to the total number of [COR_PRF_CODE_INFO](cor-prf-code-info-structure.md) structures available. + + `codeInfos` + [out] A caller-provided buffer. After the method returns, it contains an array of `COR_PRF_CODE_INFO` structures, each of which describes a block of native code. + +## Remarks + + The extents are sorted in order of increasing common intermediate language (CIL) offset. + + After `GetCodeInfo2` returns, you must verify that the `codeInfos` buffer was large enough to contain all the `COR_PRF_CODE_INFO` structures. To do this, compare the value of `cCodeInfos` with the value of the `cchName` parameter. If `cCodeInfos` divided by the size of a `COR_PRF_CODE_INFO` structure is smaller than `pcCodeInfos`, allocate a larger `codeInfos` buffer, update `cCodeInfos` with the new, larger size, and call `GetCodeInfo2` again. + + Alternatively, you can first call `GetCodeInfo2` with a zero-length `codeInfos` buffer to obtain the correct buffer size. You can then set the `codeInfos` buffer size to the value returned in `pcCodeInfos`, multiplied by the size of a `COR_PRF_CODE_INFO` structure, and call `GetCodeInfo2` again. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [GetCodeInfo3 Method](icorprofilerinfo4-getcodeinfo3-method.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md index cde690c397717..41072ad82c28b 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo3-requestprofilerdetach-method.md @@ -2,68 +2,68 @@ description: "Learn more about: ICorProfilerInfo3::RequestProfilerDetach Method" title: "ICorProfilerInfo3::RequestProfilerDetach Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo3.RequestProfilerDetach Method" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo3::RequestProfilerDetach" -helpviewer_keywords: +helpviewer_keywords: - "RequestProfilerDetach method [.NET Framework profiling]" - "ICorProfilerInfo3::RequestProfilerDetach method [.NET Framework profiling]" ms.assetid: ea102e62-0454-4477-bcf3-126773acd184 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo3::RequestProfilerDetach Method -Instructs the runtime to detach the profiler. - -## Syntax - -```cpp -HRESULT RequestProfilerDetach( - [in] DWORD dwExpectedCompletionMilliseconds); -``` - -## Parameters - - `dwExpectedCompletionMilliseconds` - [in] The length of time, in milliseconds, the common language runtime (CLR) should wait before checking to see whether it is safe to unload the profiler. - -## Return Value - - This method returns the following specific HRESULTs as well as HRESULT errors that indicate method failure. - -|HRESULT|Description| -|-------------|-----------------| -|S_OK|The detach request is valid, and the detach procedure is now continuing on another thread. When the detach is fully complete, a `ProfilerDetachSucceeded` event is issued.| -|E_CORPROF_E_CALLBACK3_REQUIRED|The profiler failed an [IUnknown::QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)) attempt for the [ICorProfilerCallback3](icorprofilercallback3-interface.md) interface, which it must implement to support the detach operation. Detach was not attempted.| -|CORPROF_E_IMMUTABLE_FLAGS_SET|Detachment is impossible because the profiler set immutable flags at startup. Detachment was not attempted; the profiler is still fully attached.| -|CORPROF_E_IRREVERSIBLE_INSTRUMENTATION_PRESENT|Detachment is impossible because the profiler used instrumented Microsoft intermediate language (MSIL) code, or inserted `enter`/`leave` hooks. Detachment was not attempted; the profiler is still fully attached.

**Note** Instrumented MSIL is code is code that is provided by the profiler using the [SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method.| -|CORPROF_E_RUNTIME_UNINITIALIZED|The runtime has not been initialized yet in the managed application. (That is, the runtime has not been fully loaded.) This error code may be returned when detachment is requested inside the profiler callback's [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md) method.| -|CORPROF_E_UNSUPPORTED_CALL_SEQUENCE|`RequestProfilerDetach` was called at an unsupported time. This occurs if the method is called on a managed thread but not from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method or from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method that cannot tolerate a garbage collection. For more information, see [CORPROF_E_UNSUPPORTED_CALL_SEQUENCE HRESULT](corprof-e-unsupported-call-sequence-hresult.md).| - -## Remarks - - During the detach procedure, the detach thread (the thread created specifically for detaching the profiler) occasionally checks whether all threads have exited the profiler’s code. The profiler should provide an estimate of how long this should take through the `dwExpectedCompletionMilliseconds` parameter. A good value to use is the typical amount of time the profiler spends inside any given `ICorProfilerCallback*` method; this value should not be less than half of the maximum amount of time the profiler expects to spend. - - The detach thread uses `dwExpectedCompletionMilliseconds` to decide how long to sleep before checking whether profiler callback code has been popped off all stacks. Although the details of the following algorithm may change in future releases of the CLR, it illustrates one way `dwExpectedCompletionMilliseconds` can be used when determining when it is safe to unload the profiler. The detach thread first sleeps for `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from the sleep, the CLR finds that profiler callback code is still present, the detach thread sleeps again, this time for two times `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from this second sleep, the detach thread finds that profiler callback code is still present, it sleeps for 10 minutes before checking again. The detach thread continues to recheck every 10 minutes. - - If the profiler specifies `dwExpectedCompletionMilliseconds` as 0 (zero), the CLR uses a default value of 5000, which means that it will perform a check after 5 seconds, again after 10 seconds, and then every 10 minutes thereafter. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v40plus](../../../../includes/net-current-v40plus-md.md)] - +Instructs the runtime to detach the profiler. + +## Syntax + +```cpp +HRESULT RequestProfilerDetach( + [in] DWORD dwExpectedCompletionMilliseconds); +``` + +## Parameters + + `dwExpectedCompletionMilliseconds` + [in] The length of time, in milliseconds, the common language runtime (CLR) should wait before checking to see whether it is safe to unload the profiler. + +## Return Value + + This method returns the following specific HRESULTs as well as HRESULT errors that indicate method failure. + +|HRESULT|Description| +|-------------|-----------------| +|S_OK|The detach request is valid, and the detach procedure is now continuing on another thread. When the detach is fully complete, a `ProfilerDetachSucceeded` event is issued.| +|E_CORPROF_E_CALLBACK3_REQUIRED|The profiler failed an [IUnknown::QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)) attempt for the [ICorProfilerCallback3](icorprofilercallback3-interface.md) interface, which it must implement to support the detach operation. Detach was not attempted.| +|CORPROF_E_IMMUTABLE_FLAGS_SET|Detachment is impossible because the profiler set immutable flags at startup. Detachment was not attempted; the profiler is still fully attached.| +|CORPROF_E_IRREVERSIBLE_INSTRUMENTATION_PRESENT|Detachment is impossible because the profiler used instrumented common intermediate language (CIL) code, or inserted `enter`/`leave` hooks. Detachment was not attempted; the profiler is still fully attached.

**Note** Instrumented CIL is code is code that is provided by the profiler using the [SetILFunctionBody](icorprofilerinfo-setilfunctionbody-method.md) method.| +|CORPROF_E_RUNTIME_UNINITIALIZED|The runtime has not been initialized yet in the managed application. (That is, the runtime has not been fully loaded.) This error code may be returned when detachment is requested inside the profiler callback's [ICorProfilerCallback::Initialize](icorprofilercallback-initialize-method.md) method.| +|CORPROF_E_UNSUPPORTED_CALL_SEQUENCE|`RequestProfilerDetach` was called at an unsupported time. This occurs if the method is called on a managed thread but not from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method or from within an [ICorProfilerCallback](icorprofilercallback-interface.md) method that cannot tolerate a garbage collection. For more information, see [CORPROF_E_UNSUPPORTED_CALL_SEQUENCE HRESULT](corprof-e-unsupported-call-sequence-hresult.md).| + +## Remarks + + During the detach procedure, the detach thread (the thread created specifically for detaching the profiler) occasionally checks whether all threads have exited the profiler’s code. The profiler should provide an estimate of how long this should take through the `dwExpectedCompletionMilliseconds` parameter. A good value to use is the typical amount of time the profiler spends inside any given `ICorProfilerCallback*` method; this value should not be less than half of the maximum amount of time the profiler expects to spend. + + The detach thread uses `dwExpectedCompletionMilliseconds` to decide how long to sleep before checking whether profiler callback code has been popped off all stacks. Although the details of the following algorithm may change in future releases of the CLR, it illustrates one way `dwExpectedCompletionMilliseconds` can be used when determining when it is safe to unload the profiler. The detach thread first sleeps for `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from the sleep, the CLR finds that profiler callback code is still present, the detach thread sleeps again, this time for two times `dwExpectedCompletionMilliseconds` milliseconds. If, after awakening from this second sleep, the detach thread finds that profiler callback code is still present, it sleeps for 10 minutes before checking again. The detach thread continues to recheck every 10 minutes. + + If the profiler specifies `dwExpectedCompletionMilliseconds` as 0 (zero), the CLR uses a default value of 5000, which means that it will perform a check after 5 seconds, again after 10 seconds, and then every 10 minutes thereafter. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v40plus](../../../../includes/net-current-v40plus-md.md)] + ## See also - [ICorProfilerInfo3 Interface](icorprofilerinfo3-interface.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md index df9595c3e32e9..5767b4f408b3c 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-getiltonativemapping2-method.md @@ -2,77 +2,77 @@ description: "Learn more about: ICorProfilerInfo4::GetILToNativeMapping2 Method" title: "ICorProfilerInfo4::GetILToNativeMapping2 Method" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo4.GetILToNativeMapping2" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo4::GetILToNativeMapping2" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo4::GetILToNativeMapping2 method [.NET Framework profiling]" - "GetILToNativeMapping2 method, ICorProfilerInfo4 interface [.NET Framework profiling]" ms.assetid: 756c1c25-08a7-4060-9798-dbeaa2f3bee5 -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo4::GetILToNativeMapping2 Method -Gets a map from Microsoft intermediate language (MSIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function. - -## Syntax - -```cpp -HRESULT GetILToNativeMapping2( - [in] FunctionID functionId, - [in] ReJITID reJitId, - [in] ULONG32 cMap, - [out] ULONG32 *pcMap, - [out, size_is(cMap), length_is(*pcMap)] - COR_DEBUG_IL_TO_NATIVE_MAP map[]); -``` - -## Parameters - - `functionId` - [in] The ID of the function that contains the code. - - `pReJitId` - [in] The identity of the JIT-recompiled function. The identity must be zero in .NET Framework 4.5. - - `cMap` - [in] The maximum size of the `map` array. - - `pcMap` - [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. - - `map` - [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping2` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. - -## Remarks - - `GetILToNativeMapping2` is similar to the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method, except that it will allow the profiler to specify the ID of the recompiled function in future releases. - +Gets a map from common intermediate language (CIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function. + +## Syntax + +```cpp +HRESULT GetILToNativeMapping2( + [in] FunctionID functionId, + [in] ReJITID reJitId, + [in] ULONG32 cMap, + [out] ULONG32 *pcMap, + [out, size_is(cMap), length_is(*pcMap)] + COR_DEBUG_IL_TO_NATIVE_MAP map[]); +``` + +## Parameters + + `functionId` + [in] The ID of the function that contains the code. + + `pReJitId` + [in] The identity of the JIT-recompiled function. The identity must be zero in .NET Framework 4.5. + + `cMap` + [in] The maximum size of the `map` array. + + `pcMap` + [out] The total number of available COR_DEBUG_IL_TO_NATIVE_MAP structures. + + `map` + [out] An array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures, each of which specifies the offsets. After the `GetILToNativeMapping2` method returns, `map` will contain some or all of the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. + +## Remarks + + `GetILToNativeMapping2` is similar to the [ICorProfilerInfo::GetILToNativeMapping](icorprofilerinfo-getiltonativemapping-method.md) method, except that it will allow the profiler to specify the ID of the recompiled function in future releases. + > [!NOTE] -> The [ICorProfilerFunctionControl::SetILInstrumentedCodeMap](icorprofilerfunctioncontrol-setilinstrumentedcodemap-method.md) method is not implemented in .NET Framework 4.5, so functions that have been JIT-recompiled cannot have an IL-to-native mapping that differs from the originally compiled function. As such, `GetILToNativeMapping2` cannot be called with a nonzero JIT-recompiled ID in .NET Framework 4.5. - - The `GetILToNativeMapping2` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. - - After `GetILToNativeMapping2` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping2` again. - - Alternatively, you can first call `GetILToNativeMapping2` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping2` again. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] - +> The [ICorProfilerFunctionControl::SetILInstrumentedCodeMap](icorprofilerfunctioncontrol-setilinstrumentedcodemap-method.md) method is not implemented in .NET Framework 4.5, so functions that have been JIT-recompiled cannot have an IL-to-native mapping that differs from the originally compiled function. As such, `GetILToNativeMapping2` cannot be called with a nonzero JIT-recompiled ID in .NET Framework 4.5. + + The `GetILToNativeMapping2` method returns an array of `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To convey that certain ranges of native instructions correspond to special regions of code (for example, the prolog), an entry in the array can have its `ilOffset` field set to a value of the [CorDebugIlToNativeMappingTypes](../debugging/cordebugiltonativemappingtypes-enumeration.md) enumeration. + + After `GetILToNativeMapping2` returns, you must verify that the `map` buffer was large enough to contain all the `COR_DEBUG_IL_TO_NATIVE_MAP` structures. To do this, compare the value of `cMap` with the value of the `pcMap` parameter. If the `pcMap` value, when it is multiplied by the size of a `COR_DEBUG_IL_TO_NATIVE_MAP` structure, is larger than `cMap`, allocate a larger `map` buffer, update `cMap` with the new, larger size, and call `GetILToNativeMapping2` again. + + Alternatively, you can first call `GetILToNativeMapping2` with a zero-length `map` buffer to obtain the correct buffer size. You can then set the buffer size to the value returned in `pcMap` and call `GetILToNativeMapping2` again. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] + ## See also - [GetILToNativeMapping Method](icorprofilerinfo-getiltonativemapping-method.md) diff --git a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md index b68c3935504bf..72cdbcf28e66e 100644 --- a/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md +++ b/docs/framework/unmanaged-api/profiling/icorprofilerinfo4-interface.md @@ -2,53 +2,53 @@ description: "Learn more about: ICorProfilerInfo4 Interface" title: "ICorProfilerInfo4 Interface" ms.date: "03/30/2017" -api_name: +api_name: - "ICorProfilerInfo4" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "ICorProfilerInfo4" -helpviewer_keywords: +helpviewer_keywords: - "ICorProfilerInfo4 interface [.NET Framework profiling]" ms.assetid: 80a5308e-c22f-4201-ba89-31cc8562515b -topic_type: +topic_type: - "apiref" --- # ICorProfilerInfo4 Interface -Provides methods that code profilers use to communicate with the common language runtime (CLR) to control event monitoring and request information. . The `ICorProfilerInfo4` interface is an extension of the other `ICorProfilerInfo` interfaces. It provides new methods to support just-in-time (JIT) recompilation, added in .NET Framework 4.5. - -## Methods - -|Method|Description| -|------------|-----------------| -|[EnumJITedFunctions2 Method](icorprofilerinfo4-enumjitedfunctions2-method.md)|Returns an enumerator for all functions that were previously JIT-compiled and JIT-recompiled.| -|[EnumThreads Method](icorprofilerinfo4-enumthreads-method.md)|Gets an enumerator that provides methods to sequentially iterate through the collection of all managed threads in the profiled process.| -|[GetCodeInfo3 Method](icorprofilerinfo4-getcodeinfo3-method.md)|Gets the extents of native code associated with the JIT-recompiled version of the specified function.| -|[GetFunctionFromIP2 Method](icorprofilerinfo4-getfunctionfromip2-method.md)|Maps a managed code instruction pointer to the JIT-recompiled version of a specified function.| -|[GetILToNativeMapping2 Method](icorprofilerinfo4-getiltonativemapping2-method.md)|Gets a map from Microsoft intermediate language (MSIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function .| -|[GetObjectSize2 Method](icorprofilerinfo4-getobjectsize2-method.md)|Returns the size of a specified object.| -|[GetReJITIDs Method](icorprofilerinfo4-getrejitids-method.md)|Returns an array of IDs that identify all JIT-recompiled versions of the specified function that are still allocated.| -|[InitializeCurrentThread Method](icorprofilerinfo4-initializecurrentthread-method.md)|Initializes the current thread in advance of subsequent profiler API calls on the same thread, so that deadlock can be avoided.| -|[RequestReJIT Method](icorprofilerinfo4-requestrejit-method.md)|Requests a JIT recompilation of all instances of the specified functions.| -|[RequestRevert Method](icorprofilerinfo4-requestrevert-method.md)|Reverts all instances of the specified functions to their original versions.| - -## Remarks - - The CLR implements the methods of the `ICorProfilerInfo4` interface by using the free-threaded model. Each method returns an HRESULT to indicate success or failure. For a list of possible return codes, see the CorError.h file. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] - +Provides methods that code profilers use to communicate with the common language runtime (CLR) to control event monitoring and request information. . The `ICorProfilerInfo4` interface is an extension of the other `ICorProfilerInfo` interfaces. It provides new methods to support just-in-time (JIT) recompilation, added in .NET Framework 4.5. + +## Methods + +|Method|Description| +|------------|-----------------| +|[EnumJITedFunctions2 Method](icorprofilerinfo4-enumjitedfunctions2-method.md)|Returns an enumerator for all functions that were previously JIT-compiled and JIT-recompiled.| +|[EnumThreads Method](icorprofilerinfo4-enumthreads-method.md)|Gets an enumerator that provides methods to sequentially iterate through the collection of all managed threads in the profiled process.| +|[GetCodeInfo3 Method](icorprofilerinfo4-getcodeinfo3-method.md)|Gets the extents of native code associated with the JIT-recompiled version of the specified function.| +|[GetFunctionFromIP2 Method](icorprofilerinfo4-getfunctionfromip2-method.md)|Maps a managed code instruction pointer to the JIT-recompiled version of a specified function.| +|[GetILToNativeMapping2 Method](icorprofilerinfo4-getiltonativemapping2-method.md)|Gets a map from common intermediate language (CIL) offsets to native offsets for the code contained in the JIT-recompiled version of the specified function .| +|[GetObjectSize2 Method](icorprofilerinfo4-getobjectsize2-method.md)|Returns the size of a specified object.| +|[GetReJITIDs Method](icorprofilerinfo4-getrejitids-method.md)|Returns an array of IDs that identify all JIT-recompiled versions of the specified function that are still allocated.| +|[InitializeCurrentThread Method](icorprofilerinfo4-initializecurrentthread-method.md)|Initializes the current thread in advance of subsequent profiler API calls on the same thread, so that deadlock can be avoided.| +|[RequestReJIT Method](icorprofilerinfo4-requestrejit-method.md)|Requests a JIT recompilation of all instances of the specified functions.| +|[RequestRevert Method](icorprofilerinfo4-requestrevert-method.md)|Reverts all instances of the specified functions to their original versions.| + +## Remarks + + The CLR implements the methods of the `ICorProfilerInfo4` interface by using the free-threaded model. Each method returns an HRESULT to indicate success or failure. For a list of possible return codes, see the CorError.h file. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v45plus](../../../../includes/net-current-v45plus-md.md)] + ## See also - [Profiling Interfaces](profiling-interfaces.md) diff --git a/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md b/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md index e1c9ac27cb39b..3242f2359b9af 100644 --- a/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md +++ b/docs/framework/unmanaged-api/profiling/imethodmalloc-alloc-method.md @@ -20,7 +20,7 @@ topic_type: # IMethodMalloc::Alloc Method -Attempts to allocate a specified amount of memory for a new Microsoft intermediate language (MSIL) function body. +Attempts to allocate a specified amount of memory for a new common intermediate language (CIL) function body. ## Syntax diff --git a/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md b/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md index 661b6c3ac8932..e5ed65cdf302d 100644 --- a/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md +++ b/docs/framework/unmanaged-api/profiling/imethodmalloc-interface.md @@ -2,47 +2,47 @@ description: "Learn more about: IMethodMalloc Interface" title: "IMethodMalloc Interface" ms.date: "03/30/2017" -api_name: +api_name: - "IMethodMalloc" -api_location: +api_location: - "mscorwks.dll" -api_type: +api_type: - "COM" -f1_keywords: +f1_keywords: - "IMethodMalloc" -helpviewer_keywords: +helpviewer_keywords: - "IMethodMalloc interface [.NET Framework profiling]" ms.assetid: 8c8ab5dc-557c-473a-82f2-6e403eca7dac -topic_type: +topic_type: - "apiref" --- # IMethodMalloc Interface -Provides a method to allocate memory for a new Microsoft intermediate language (MSIL) function body. - +Provides a method to allocate memory for a new common intermediate language (CIL) function body. + > [!NOTE] -> The `IMethodMalloc` interface is a simple memory allocator. It allows you to allocate memory, but not to free it. - -## Methods - -|Method|Description| -|------------|-----------------| -|[Alloc Method](imethodmalloc-alloc-method.md)|Attempts to allocate a specified amount of memory for a new MSIL function body.| - -## Remarks - - Each allocator is module-specific and ensures that the function body will be at a positive offset from the base of the module. Memory above the base of a module can be precious, so the allocator should be used to allocate memory only for a function body. - -## Requirements - - **Platforms:** See [System Requirements](../../get-started/system-requirements.md). - - **Header:** CorProf.idl, CorProf.h - - **Library:** CorGuids.lib - - **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] - +> The `IMethodMalloc` interface is a simple memory allocator. It allows you to allocate memory, but not to free it. + +## Methods + +|Method|Description| +|------------|-----------------| +|[Alloc Method](imethodmalloc-alloc-method.md)|Attempts to allocate a specified amount of memory for a new CIL function body.| + +## Remarks + + Each allocator is module-specific and ensures that the function body will be at a positive offset from the base of the module. Memory above the base of a module can be precious, so the allocator should be used to allocate memory only for a function body. + +## Requirements + + **Platforms:** See [System Requirements](../../get-started/system-requirements.md). + + **Header:** CorProf.idl, CorProf.h + + **Library:** CorGuids.lib + + **.NET Framework Versions:** [!INCLUDE[net_current_v20plus](../../../../includes/net-current-v20plus-md.md)] + ## See also - [Profiling Interfaces](profiling-interfaces.md) diff --git a/docs/framework/unmanaged-api/profiling/profiling-interfaces.md b/docs/framework/unmanaged-api/profiling/profiling-interfaces.md index 66fa3f2db12bd..4a8a0a92a71bd 100644 --- a/docs/framework/unmanaged-api/profiling/profiling-interfaces.md +++ b/docs/framework/unmanaged-api/profiling/profiling-interfaces.md @@ -105,7 +105,7 @@ Provides methods to sequentially iterate through a collection of frozen objects Provides methods to sequentially iterate through a collection of threads in the CLR. [IMethodMalloc Interface](imethodmalloc-interface.md)\ -Provides the [Alloc](imethodmalloc-alloc-method.md) method to allocate memory for a new Microsoft intermediate language (MSIL) function body. +Provides the [Alloc](imethodmalloc-alloc-method.md) method to allocate memory for a new common intermediate language (CIL) function body. ## Related Sections diff --git a/docs/framework/unmanaged-api/profiling/profiling-overview.md b/docs/framework/unmanaged-api/profiling/profiling-overview.md index c70c1aaaaca96..38f91aa7b0e24 100644 --- a/docs/framework/unmanaged-api/profiling/profiling-overview.md +++ b/docs/framework/unmanaged-api/profiling/profiling-overview.md @@ -35,9 +35,9 @@ A profiler is a tool that monitors the execution of another application. A commo Traditional profiling tools focus on measuring the execution of the application. That is, they measure the time that is spent in each function or the memory usage of the application over time. The profiling API targets a broader class of diagnostic tools such as code-coverage utilities and even advanced debugging aids. These uses are all diagnostic in nature. The profiling API not only measures but also monitors the execution of an application. For this reason, the profiling API should never be used by the application itself, and the application’s execution should not depend on (or be affected by) the profiler. -Profiling a CLR application requires more support than profiling conventionally compiled machine code. This is because the CLR introduces concepts such as application domains, garbage collection, managed exception handling, just-in-time (JIT) compilation of code (converting Microsoft intermediate language, or MSIL, code into native machine code), and similar features. Conventional profiling mechanisms cannot identify or provide useful information about these features. The profiling API provides this missing information efficiently, with minimal effect on the performance of the CLR and the profiled application. +Profiling a CLR application requires more support than profiling conventionally compiled machine code. This is because the CLR introduces concepts such as application domains, garbage collection, managed exception handling, just-in-time (JIT) compilation of code (converting common intermediate language, or CIL, code into native machine code), and similar features. Conventional profiling mechanisms cannot identify or provide useful information about these features. The profiling API provides this missing information efficiently, with minimal effect on the performance of the CLR and the profiled application. -JIT compilation at run time provides good opportunities for profiling. The profiling API enables a profiler to change the in-memory MSIL code stream for a routine before it is JIT-compiled. In this manner, the profiler can dynamically add instrumentation code to particular routines that need deeper investigation. Although this approach is possible in conventional scenarios, it is much easier to implement for the CLR by using the profiling API. +JIT compilation at run time provides good opportunities for profiling. The profiling API enables a profiler to change the in-memory CIL code stream for a routine before it is JIT-compiled. In this manner, the profiler can dynamically add instrumentation code to particular routines that need deeper investigation. Although this approach is possible in conventional scenarios, it is much easier to implement for the CLR by using the profiling API. ## The Profiling API @@ -138,11 +138,11 @@ A review of the CLR profiling API may create the impression that you can write a Although this is possible from a design perspective, the profiling API does not support managed components. A CLR profiler must be completely unmanaged. Attempts to combine managed and unmanaged code in a CLR profiler may cause access violations, program failure, or deadlocks. The managed components of the profiler will fire events back to their unmanaged components, which would subsequently call the managed components again, resulting in circular references. -The only location where a CLR profiler can call managed code safely is in the Microsoft intermediate language (MSIL) body of a method. The recommended practice for modifying the MSIL body is to use the JIT recompilation methods in the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interface. +The only location where a CLR profiler can call managed code safely is in the common intermediate language (CIL) body of a method. The recommended practice for modifying the CIL body is to use the JIT recompilation methods in the [ICorProfilerCallback4](icorprofilercallback4-interface.md) interface. -It is also possible to use the older instrumentation methods to modify MSIL. Before the just-in-time (JIT) compilation of a function is completed, the profiler can insert managed calls in the MSIL body of a method and then JIT-compile it (see the [ICorProfilerInfo::GetILFunctionBody](icorprofilerinfo-getilfunctionbody-method.md) method). This technique can successfully be used for selective instrumentation of managed code, or to gather statistics and performance data about the JIT. +It is also possible to use the older instrumentation methods to modify CIL. Before the just-in-time (JIT) compilation of a function is completed, the profiler can insert managed calls in the CIL body of a method and then JIT-compile it (see the [ICorProfilerInfo::GetILFunctionBody](icorprofilerinfo-getilfunctionbody-method.md) method). This technique can successfully be used for selective instrumentation of managed code, or to gather statistics and performance data about the JIT. -Alternatively, a code profiler can insert native hooks in the MSIL body of every managed function that calls into unmanaged code. This technique can be used for instrumentation and coverage. For example, a code profiler could insert instrumentation hooks after every MSIL block to ensure that the block has been executed. The modification of the MSIL body of a method is a very delicate operation, and there are many factors that should be taken into consideration. +Alternatively, a code profiler can insert native hooks in the CIL body of every managed function that calls into unmanaged code. This technique can be used for instrumentation and coverage. For example, a code profiler could insert instrumentation hooks after every CIL block to ensure that the block has been executed. The modification of the CIL body of a method is a very delicate operation, and there are many factors that should be taken into consideration. ## Profiling Unmanaged Code diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index 882a79fe27371..d2f7e7f9e5455 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -736,7 +736,7 @@ In .NET Framework 4.7 and earlier versions, ASP.NET allowed developers to store - [Windows Forms](#wf47) - [Windows Presentation Foundation (WPF)](#WPF47) -For a list of new APIs added to .NET Framework 4.7, see [.NET Framework 4.7 API Changes](https://github.com/Microsoft/dotnet/blob/master/releases/net47/dotnet47-api-changes.md) on GitHub. For a list of feature improvements and bug fixes in .NET Framework 4.7, see [.NET Framework 4.7 List of Changes](https://github.com/Microsoft/dotnet/blob/master/releases/net47/dotnet47-changes.md) on GitHub. For more information, see [Announcing .NET Framework 4.7](https://devblogs.microsoft.com/dotnet/announcing-the-net-framework-4-7/) in the .NET blog. +For a list of new APIs added to .NET Framework 4.7, see [.NET Framework 4.7 API Changes](https://github.com/Microsoft/dotnet/blob/main/releases/net47/dotnet47-api-changes.md) on GitHub. For a list of feature improvements and bug fixes in .NET Framework 4.7, see [.NET Framework 4.7 List of Changes](https://github.com/Microsoft/dotnet/blob/main/releases/net47/dotnet47-changes.md) on GitHub. For more information, see [Announcing .NET Framework 4.7](https://devblogs.microsoft.com/dotnet/announcing-the-net-framework-4-7/) in the .NET blog. @@ -1235,7 +1235,7 @@ In previous versions of .NET Framework, WPF applications can't opt into the focu **Per-monitor DPI** -To support the recent proliferation of high-DPI and hybrid-DPI environments for WPF apps, WPF in .NET Framework 4.6.2 enables per-monitor awareness. See the [samples and developer guide](https://github.com/Microsoft/WPF-Samples/tree/master/PerMonitorDPI) on GitHub for more information about how to enable your WPF app to become per-monitor DPI aware. +To support the recent proliferation of high-DPI and hybrid-DPI environments for WPF apps, WPF in .NET Framework 4.6.2 enables per-monitor awareness. See the [samples and developer guide](https://github.com/Microsoft/WPF-Samples/tree/main/PerMonitorDPI) on GitHub for more information about how to enable your WPF app to become per-monitor DPI aware. In previous versions of .NET Framework, WPF apps are system-DPI aware. In other words, the application's UI is scaled by the OS as appropriate, depending on the DPI of the monitor on which the app is rendered. @@ -1322,11 +1322,11 @@ The *unmanaged debugging API* has been enhanced in .NET Framework 4.6.2 to perfo For more information on .NET Framework 4.6.1, see the following topics: -- [.NET Framework 4.6.1 list of changes](https://github.com/Microsoft/dotnet/blob/master/releases/net461/dotnet461-changes.md) +- [.NET Framework 4.6.1 list of changes](https://github.com/Microsoft/dotnet/blob/main/releases/net461/dotnet461-changes.md) - [Application Compatibility in 4.6.1](../migration-guide/application-compatibility.md) -- [.NET Framework API diff](https://github.com/Microsoft/dotnet/blob/master/releases/net461/dotnet461-api-changes.md) (on GitHub) +- [.NET Framework API diff](https://github.com/Microsoft/dotnet/blob/main/releases/net461/dotnet461-api-changes.md) (on GitHub) diff --git a/docs/fsharp/language-reference/operator-overloading.md b/docs/fsharp/language-reference/operator-overloading.md index 1c4521b831f49..4efd8dae1dbd8 100644 --- a/docs/fsharp/language-reference/operator-overloading.md +++ b/docs/fsharp/language-reference/operator-overloading.md @@ -45,7 +45,7 @@ A table that shows the precedence of all operators in F# can be found in [Symbol ## Overloaded Operator Names -When the F# compiler compiles an operator expression, it generates a method that has a compiler-generated name for that operator. This is the name that appears in the Microsoft intermediate language (MSIL) for the method, and also in reflection and IntelliSense. You do not normally need to use these names in F# code. +When the F# compiler compiles an operator expression, it generates a method that has a compiler-generated name for that operator. This is the name that appears in the common intermediate language (CIL) for the method, and also in reflection and IntelliSense. You do not normally need to use these names in F# code. The following table shows the standard operators and their corresponding generated names. diff --git a/docs/fsharp/language-reference/type-abbreviations.md b/docs/fsharp/language-reference/type-abbreviations.md index 58d4e021ae726..1d0df25d72af5 100644 --- a/docs/fsharp/language-reference/type-abbreviations.md +++ b/docs/fsharp/language-reference/type-abbreviations.md @@ -3,7 +3,7 @@ title: Type Abbreviations description: Learn about F# type abbreviations to give a type a more meaningful name in order to make code easier to read. ms.date: 05/16/2016 --- -# Type Abbreviations +# Type abbreviations A *type abbreviation* is an alias or alternate name for a type. @@ -27,7 +27,7 @@ Type abbreviations can include generic parameters, as in the following code. In the previous code, `Transform` is a type abbreviation that represents a function that takes a single argument of any type and that returns a single value of that same type. -Type abbreviations are not preserved in the .NET Framework MSIL code. Therefore, when you use an F# assembly from another .NET Framework language, you must use the underlying type name for a type abbreviation. +Type abbreviations are not preserved in common intermediate language (CIL) code. Therefore, when you use an F# assembly from another .NET language, you must use the underlying type name for a type abbreviation. Type abbreviations can also be used on units of measure. For more information, see [Units of Measure](units-of-measure.md). diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1047.md b/docs/fundamentals/code-analysis/quality-rules/ca1047.md index 5e6722ef8b9b3..168272c2db005 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1047.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1047.md @@ -32,7 +32,7 @@ A public type is `sealed` (`NotInheritable` in Visual basic) and declares a prot Types declare protected members so that inheriting types can access or override the member. By definition, you cannot inherit from a sealed type, which means that protected methods on sealed types cannot be called. -The C# compiler issues a warning for this error. +The C# compiler emits warning [CS0628](../../../csharp/misc/cs0628.md) instead of CA1047 for this situation. ## How to fix violations diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1810.md b/docs/fundamentals/code-analysis/quality-rules/ca1810.md index be4fe44080d63..ed296fcf359d7 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1810.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1810.md @@ -32,7 +32,7 @@ A reference type declares an explicit static constructor. When a type declares an explicit static constructor, the just-in-time (JIT) compiler adds a check to each static method and instance constructor of the type to make sure that the static constructor was previously called. Static initialization is triggered when any static member is accessed or when an instance of the type is created. However, static initialization is not triggered if you declare a variable of the type but do not use it, which can be important if the initialization changes global state. -When all static data is initialized inline and an explicit static constructor is not declared, Microsoft intermediate language (MSIL) compilers add the `beforefieldinit` flag and an implicit static constructor, which initializes the static data, to the MSIL type definition. When the JIT compiler encounters the `beforefieldinit` flag, most of the time the static constructor checks are not added. Static initialization is guaranteed to occur at some time before any static fields are accessed but not before a static method or instance constructor is invoked. Note that static initialization can occur at any time after a variable of the type is declared. +When all static data is initialized inline and an explicit static constructor is not declared, common intermediate language (CIL) compilers add the `beforefieldinit` flag and an implicit static constructor, which initializes the static data, to the CIL type definition. When the JIT compiler encounters the `beforefieldinit` flag, most of the time the static constructor checks are not added. Static initialization is guaranteed to occur at some time before any static fields are accessed but not before a static method or instance constructor is invoked. Note that static initialization can occur at any time after a variable of the type is declared. Static constructor checks can decrease performance. Often a static constructor is used only to initialize static fields, in which case you must only make sure that static initialization occurs before the first access of a static field. The `beforefieldinit` behavior is appropriate for these and most other types. It is only inappropriate when static initialization affects global state and one of the following is true: @@ -78,7 +78,7 @@ The following example shows a type, `StaticConstructor`, that violates the rule :::code language="vb" source="snippets/vb/all-rules/ca1810-initialize-reference-type-static-fields-inline_1.vb"::: -Note the addition of the `beforefieldinit` flag on the MSIL definition for the `NoStaticConstructor` class. +Note the addition of the `beforefieldinit` flag on the CIL definition for the `NoStaticConstructor` class. ```il .class public auto ansi StaticConstructor diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1820.md b/docs/fundamentals/code-analysis/quality-rules/ca1820.md index 8f96e179f5fd5..cc581da0d0515 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1820.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1820.md @@ -27,7 +27,7 @@ A string is compared to the empty string by using property or the method is faster than using . This is because executes significantly more MSIL instructions than either or the number of instructions executed to retrieve the property value and compare it to zero. +Comparing strings using the property or the method is faster than using . This is because executes significantly more CIL instructions than either or the number of instructions executed to retrieve the property value and compare it to zero. For null strings, and `.Length == 0` behave differently. If you try to get the value of the property on a null string, the common language runtime throws a . If you perform a comparison between a null string and the empty string, the common language runtime does not throw an exception and returns `false`. Testing for null does not significantly affect the relative performance of these two approaches. When targeting .NET Framework 2.0 or later, use the method. Otherwise, use the == 0 comparison whenever possible. diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2207.md b/docs/fundamentals/code-analysis/quality-rules/ca2207.md index 584eaebe98c57..b97b850371006 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca2207.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca2207.md @@ -29,7 +29,7 @@ A value-type declares an explicit static constructor. When a value-type is declared, it undergoes a default initialization where all value-type fields are set to zero and all reference-type fields are set to `null` (`Nothing` in Visual Basic). An explicit static constructor is only guaranteed to run before an instance constructor or static member of the type is called. Therefore, if the type is created without calling an instance constructor, the static constructor is not guaranteed to run. -If all static data is initialized inline and no explicit static constructor is declared, the C# and Visual Basic compilers add the `beforefieldinit` flag to the MSIL class definition. The compilers also add a private static constructor that contains the static initialization code. This private static constructor is guaranteed to run before any static fields of the type are accessed. +If all static data is initialized inline and no explicit static constructor is declared, the C# and Visual Basic compilers add the `beforefieldinit` flag to the CIL class definition. The compilers also add a private static constructor that contains the static initialization code. This private static constructor is guaranteed to run before any static fields of the type are accessed. ## How to fix violations diff --git a/docs/fundamentals/networking/includes/ip-endpoint.md b/docs/fundamentals/networking/includes/ip-endpoint.md index 2305425594dc2..2b3c0efa97d09 100644 --- a/docs/fundamentals/networking/includes/ip-endpoint.md +++ b/docs/fundamentals/networking/includes/ip-endpoint.md @@ -1,5 +1,5 @@ --- -ms.date: 08/24/2022 +ms.date: 04/17/2024 author: IEvangelist ms.author: dapine ms.topic: include @@ -19,7 +19,14 @@ IPAddress ipAddress = ipHostInfo.AddressList[0]; ``` > [!TIP] -> For manual testing and debugging purposes, you can typically use the method to get given the value to resolve the localhost name to an IP address. +> For manual testing and debugging purposes, you can typically use the method with the resulting host name from the value to resolve the localhost name to an IP address. Consider the following code snippet: +> +> ```csharp +> var hostName = Dns.GetHostName(); +> IPHostEntry localhost = await Dns.GetHostEntryAsync(hostName); +> // This is the IP address of the local machine +> IPAddress localIpAddress = localhost.AddressList[0]; +> ``` The Internet Assigned Numbers Authority (IANA) defines port numbers for common services. For more information, see [IANA: Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml)). Other services can have registered port numbers in the range 1,024 to 65,535. The following code combines the IP address for `host.contoso.com` with a port number to create a remote endpoint for a connection. diff --git a/docs/fundamentals/networking/sockets/tcp-classes.md b/docs/fundamentals/networking/sockets/tcp-classes.md index 3d0260d1349e5..8d8d2651edce5 100644 --- a/docs/fundamentals/networking/sockets/tcp-classes.md +++ b/docs/fundamentals/networking/sockets/tcp-classes.md @@ -3,7 +3,7 @@ title: Use TcpClient and TcpListener description: Learn how to use the TcpClient class to create a socket to request and receive data using TCP in .NET. author: IEvangelist ms.author: dapine -ms.date: 08/24/2022 +ms.date: 04/17/2024 helpviewer_keywords: - "protocols, TCP" - "network resources, TCP" diff --git a/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md b/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md index 1157bcdb49e6f..78d7bd44ce29c 100644 --- a/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md +++ b/docs/fundamentals/runtime-libraries/system-collections-generic-list{t}.md @@ -39,7 +39,7 @@ If a value type is used for type `T`, the compiler generates an implementation o Make certain the value type used for type `T` implements the generic interface. If not, methods such as must call the method, which boxes the affected list element. If the value type implements the interface and you own the source code, also implement the generic interface to prevent the and methods from boxing list elements. If you do not own the source code, pass an object to the and methods. -It's to your advantage to use the type-specific implementation of the class instead of using the class or writing a strongly typed wrapper collection yourself. That's because your implementation must do what .NET does for you already, and the .NET runtime can share Microsoft intermediate language code and metadata, which your implementation cannot. +It's to your advantage to use the type-specific implementation of the class instead of using the class or writing a strongly typed wrapper collection yourself. That's because your implementation must do what .NET does for you already, and the .NET runtime can share common intermediate language code and metadata, which your implementation cannot. ## F# considerations diff --git a/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md b/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md index 0d08dc01dd94e..b83d1d4072e7c 100644 --- a/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md +++ b/docs/fundamentals/runtime-libraries/system-invalidoperationexception.md @@ -247,7 +247,7 @@ Calling the ### Dynamic cross-application domain field access -The Microsoft intermediate language (MSIL) instruction throws an exception if the object containing the field whose address you are trying to retrieve is not within the application domain in which your code is executing. The address of a field can only be accessed from the application domain in which it resides. +The common intermediate language (CIL) instruction throws an exception if the object containing the field whose address you are trying to retrieve is not within the application domain in which your code is executing. The address of a field can only be accessed from the application domain in which it resides. ## Throw an InvalidOperationException exception diff --git a/docs/fundamentals/runtime-libraries/system-net-http-httpclient.md b/docs/fundamentals/runtime-libraries/system-net-http-httpclient.md index f8ae7a57c4727..f38aaf91a2a7d 100644 --- a/docs/fundamentals/runtime-libraries/system-net-http-httpclient.md +++ b/docs/fundamentals/runtime-libraries/system-net-http-httpclient.md @@ -79,7 +79,7 @@ If this change is undesirable, on Windows you can continue to use 's behavior are customizable through [Runtime configuration options](/dotnet/core/run-time-config/networking). However, the behavior of these switches differs through .NET versions. For example, in .NET Core 2.1 - 3.1, you can configure whether is used by default, but that option is no longer available starting in .NET 5.0. +Certain aspects of 's behavior are customizable through [Runtime configuration options](/dotnet/core/run-time-config/networking). However, the behavior of these switches differs through .NET versions. For example, in .NET Core 2.1 - 3.1, you can configure whether is used by default, but that option is no longer available starting in .NET 5. ## Connection pooling diff --git a/docs/fundamentals/runtime-libraries/system-net-http-httpclienthandler.md b/docs/fundamentals/runtime-libraries/system-net-http-httpclienthandler.md index fc9e85eeee52f..e74b161f4f5ab 100644 --- a/docs/fundamentals/runtime-libraries/system-net-http-httpclienthandler.md +++ b/docs/fundamentals/runtime-libraries/system-net-http-httpclienthandler.md @@ -12,29 +12,3 @@ The class and classes derived from it e ## HttpClientHandler in .NET Core Starting in .NET Core 2.1, the implementation of the `HttpClientHandler` class was changed to be based on the cross-platform HTTP protocol stack used by the class. Prior to .NET Core 2.1, the `HttpClientHandler` class used older HTTP protocol stacks ( on Windows and `CurlHandler`, an internal class implemented on top of Linux's native `libcurl` component, on Linux). - -On .NET Core 2.1 - 3.1 only, you can configure your app to use the older HTTP protocol stacks in one of the following three ways: - -- Call the method: - - ```csharp - AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false); - ``` - - ```vb - AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", False) - ``` - -- Define the `System.Net.Http.UseSocketsHttpHandler` switch in the *.netcore.runtimeconfig.json* configuration file: - - ```json - "runtimeOptions": { - "configProperties": { - "System.Net.Http.UseSocketsHttpHandler": false - } - } - ``` - -- Define an environment variable named `DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER` and set it to either `false` or **0**. - -These configuration options are not available starting with .NET 5. diff --git a/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md b/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md index dc22f9c61270f..4d1dffa1f5a7a 100644 --- a/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md +++ b/docs/fundamentals/runtime-libraries/system-reflection-emit-methodbuilder.md @@ -7,7 +7,7 @@ ms.date: 12/31/2023 [!INCLUDE [context](includes/context.md)] -The class is used to fully describe a method in Microsoft intermediate language (MSIL), including the name, attributes, signature, and method body. It is used in conjunction with the class to create classes at runtime. +The class is used to fully describe a method in common intermediate language (CIL), including the name, attributes, signature, and method body. It is used in conjunction with the class to create classes at runtime. You can use reflection emit to define global methods and to define methods as type members. The APIs that define methods return objects. diff --git a/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md b/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md index 9ac893bb8ab53..a38d5066179a4 100644 --- a/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md +++ b/docs/fundamentals/runtime-libraries/system-text-regularexpressions-regex.md @@ -10,17 +10,18 @@ dev_langs: [!INCLUDE [context](includes/context.md)] -The class represents .NET's regular expression engine. It can be used to quickly parse large amounts of text to find specific character patterns; to extract, edit, replace, or delete text substrings; and to add the extracted strings to a collection to generate a report. +The class represents .NET's regular expression engine. You can use this class to: -> [!NOTE] -> If you want to validate a string by determining whether it conforms to a particular pattern, you can use the class. - -To use regular expressions, you define the pattern that you want to identify in a text stream by using the syntax documented in [Regular Expression Language - Quick Reference](../../standard/base-types/regular-expression-language-quick-reference.md). Next, you can optionally instantiate a object. Finally, you call a method that performs some operation, such as replacing text that matches the regular expression pattern, or identifying a pattern match. +- Quickly parse large amounts of text to find specific character patterns. +- Extract, edit, replace, or delete text substrings. +- Add the extracted strings to a collection to generate a report. > [!NOTE] -> For some common regular expression patterns, see [Regular Expression Examples](/dotnet/standard/base-types/regular-expression-examples). There are also a number of online libraries of regular expression patterns, such as the one at [Regular-Expressions.info](https://www.regular-expressions.info/examples.html). +> If you want to validate a string by determining whether it conforms to a particular regular expression pattern, you can use the class. + +To use regular expressions, you define the pattern that you want to identify in a text stream by using the syntax documented in [Regular expression language - quick reference](../../standard/base-types/regular-expression-language-quick-reference.md). Next, you can optionally instantiate a object. Finally, you call a method that performs some operation, such as replacing text that matches the regular expression pattern, or identifying a pattern match. -For more information about the regular expression language, see [Regular Expression Language - Quick Reference](../../standard/base-types/regular-expression-language-quick-reference.md) or download and print one of these brochures: +For more information about the regular expression language, see [Regular expression language - quick reference](../../standard/base-types/regular-expression-language-quick-reference.md) or download and print one of these brochures: [Quick Reference in Word (.docx) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.docx) [Quick Reference in PDF (.pdf) format](https://download.microsoft.com/download/D/2/4/D240EBF6-A9BA-4E4F-A63F-AEB6DA0B921C/Regular%20expressions%20quick%20reference.pdf) @@ -70,14 +71,12 @@ Whether you decide to instantiate a In addition to its pattern-matching methods, the class includes several special-purpose methods: - The method escapes any characters that may be interpreted as regular expression operators in a regular expression or input string. - - The method removes these escape characters. - - The method creates an assembly that contains predefined regular expressions. .NET contains examples of these special-purpose assemblies in the namespace. ## Define a time-out value -.NET supports a full-featured regular expression language that provides substantial power and flexibility in pattern matching. However, the power and flexibility come at a cost: the risk of poor performance. Regular expressions that perform poorly are surprisingly easy to create. In some cases, regular expression operations that rely on excessive backtracking can appear to stop responding when they process text that nearly matches the regular expression pattern. For more information about the .NET Regular Expression engine, see [Details of Regular Expression Behavior](../../standard/base-types/details-of-regular-expression-behavior.md). For more information about excessive backtracking, see [Backtracking](../../standard/base-types/backtracking-in-regular-expressions.md). +.NET supports a full-featured regular expression language that provides substantial power and flexibility in pattern matching. However, the power and flexibility come at a cost: the risk of poor performance. Regular expressions that perform poorly are surprisingly easy to create. In some cases, regular expression operations that rely on excessive backtracking can appear to stop responding when they process text that nearly matches the regular expression pattern. For more information about the .NET Regular Expression engine, see [Details of regular expression behavior](../../standard/base-types/details-of-regular-expression-behavior.md). For more information about excessive backtracking, see [Backtracking](../../standard/base-types/backtracking-in-regular-expressions.md). Starting with .NET Framework 4.5, you can define a time-out interval for regular expression matches to limit excessive backtracking. Depending on the regular expression pattern and the input text, the execution time may exceed the specified time-out interval, but it will not spend more time backtracking than the specified time-out interval. If the regular expression engine times out, it throws a exception. In most cases, this prevents the regular expression engine from wasting processing power by trying to match text that nearly matches the regular expression pattern. It also could indicate, however, that the time-out interval has been set too low, or that the current machine load has caused an overall degradation in performance. @@ -85,43 +84,42 @@ How you handle the exception depends on the cause of the exception. If the excep You can set a time-out interval by calling the constructor when you instantiate a regular expression object. For static methods, you can set a time-out interval by calling an overload of a matching method that has a `matchTimeout` parameter. If you do not set a time-out value explicitly, the default time-out value is determined as follows: -- By using the application-wide time-out value, if one exists. This can be any time-out value that applies to the application domain in which the object is instantiated or the static method call is made. You can set the application-wide time-out value by calling the method to assign the string representation of a value to the "REGEX_DEFAULT_MATCH_TIMEOUT" property. - +- By using the application-wide time-out value, if one exists. Set the application-wide time-out value by calling the method to assign the string representation of a value to the `REGEX_DEFAULT_MATCH_TIMEOUT` property. - By using the value , if no application-wide time-out value has been set. > [!IMPORTANT] -> We recommend that you set a time-out value in all regular expression pattern-matching operations. For more information, see [Best Practices for Regular Expressions](/dotnet/standard/base-types/best-practices). +> We recommend that you set a time-out value in all regular expression pattern-matching operations. For more information, see [Best practices for regular expressions](../../standard/base-types/best-practices-regex.md). ## Examples The following example uses a regular expression to check for repeated occurrences of words in a string. The regular expression `\b(?\w+)\s+(\k)\b` can be interpreted as shown in the following table. -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start the match at a word boundary.| -|`(?\w+)`|Match one or more word characters up to a word boundary. Name this captured group `word`.| -|`\s+`|Match one or more white-space characters.| -|`(\k)`|Match the captured group that is named `word`.| -|`\b`|Match a word boundary.| +| Pattern | Description | +|----------------|-------------------------------------------------------------------------------------------| +| `\b` | Start the match at a word boundary. | +| `(?\w+)` | Match one or more word characters up to a word boundary. Name this captured group `word`. | +| `\s+` | Match one or more white-space characters. | +| `(\k)` | Match the captured group that's named `word`. | +| `\b` | Match a word boundary. | :::code language="csharp" source="./snippets/System.Text.RegularExpressions/Regex/Overview/csharp/words.cs" interactive="try-dotnet" id="Snippet0"::: :::code language="vb" source="./snippets/System.Text.RegularExpressions/Regex/Overview/vb/words.vb" id="Snippet0"::: -The following example illustrates the use of a regular expression to check whether a string either represents a currency value or has the correct format to represent a currency value. In this case, the regular expression is built dynamically from the , , , , and properties for the en-US culture. The resulting regular expression is `^\s*[\+-]?\s?\$?\s?(\d*\.?\d{2}?){1}$`. This regular expression can be interpreted as shown in the following table. - -|Pattern|Description| -|-------------|-----------------| -|`^`|Start at the beginning of the string.| -|`\s*`|Match zero or more white-space characters.| -|`[\+-]?`|Match zero or one occurrence of either the positive sign or the negative sign.| -|`\s?`|Match zero or one white-space character.| -|`\$?`|Match zero or one occurrence of the dollar sign.| -|`\s?`|Match zero or one white-space character.| -|`\d*`|Match zero or more decimal digits.| -|`\.?`|Match zero or one decimal point symbol.| -|`(\d{2})?`|Capturing group 1: Match two decimal digits zero or one time.| -|`(\d*\.?(\d{2})?){1}`|Match the pattern of integral and fractional digits separated by a decimal point symbol at least one time.| -|`$`|Match the end of the string.| +The next example illustrates the use of a regular expression to check whether a string either represents a currency value or has the correct format to represent a currency value. In this case, the regular expression is built dynamically from the , , , , and properties for the en-US culture. The resulting regular expression is `^\s*[\+-]?\s?\$?\s?(\d*\.?\d{2}?){1}$`. This regular expression can be interpreted as shown in the following table. + +| Pattern | Description | +|------------|--------------------------------------------------------------------------------| +| `^` | Start at the beginning of the string. | +| `\s*` | Match zero or more white-space characters. | +| `[\+-]?` | Match zero or one occurrence of either the positive sign or the negative sign. | +| `\s?` | Match zero or one white-space character. | +| `\$?` | Match zero or one occurrence of the dollar sign. | +| `\s?` | Match zero or one white-space character. | +| `\d*` | Match zero or more decimal digits. | +| `\.?` | Match zero or one decimal point symbol. | +| `(\d{2})?` | Capturing group 1: Match two decimal digits zero or one time. | +| `(\d*\.?(\d{2})?){1}` | Match the pattern of integral and fractional digits separated by a decimal point symbol at least one time. | +| `$` | Match the end of the string. | In this case, the regular expression assumes that a valid currency string does not contain group separator symbols, and that it has either no fractional digits or the number of fractional digits defined by the specified culture's property. diff --git a/docs/fundamentals/runtime-libraries/system-type-gettype.md b/docs/fundamentals/runtime-libraries/system-type-gettype.md index 29b2e5676e79c..7bb9efc978d09 100644 --- a/docs/fundamentals/runtime-libraries/system-type-gettype.md +++ b/docs/fundamentals/runtime-libraries/system-type-gettype.md @@ -106,7 +106,7 @@ Because this assembly is neither mscorlib.dll/System.Private.CoreLib.dll nor the Certain characters have special meanings in assembly-qualified names. If a simple type name contains these characters, the characters cause parsing errors when the simple name is part of an assembly-qualified name. To avoid the parsing errors, you must escape the special characters with a backslash before you can pass the assembly-qualified name to the method. For example, if a type is named `Strange]Type`, the escape character must be added ahead of the square bracket as follows: `Strange\]Type`. > [!NOTE] -> Names with such special characters cannot be created in Visual Basic or C#, but can be created by using Microsoft intermediate language (MSIL) or by emitting dynamic assemblies. +> Names with such special characters cannot be created in Visual Basic or C#, but can be created by using common intermediate language (CIL) or by emitting dynamic assemblies. The following table shows the special characters for type names. diff --git a/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md b/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md index ef077f587f84b..005e23cf3b7e1 100644 --- a/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md +++ b/docs/fundamentals/runtime-libraries/system-type-makegenerictype.md @@ -44,7 +44,7 @@ If the parameter list of the enclosing type has more than one type parameter, al To construct a generic type from the generic type definition for a nested type, call the method with the array formed by concatenating the type argument arrays of all the enclosing types, beginning with the outermost generic type, and ending with the type argument array of the nested type itself, if it has type parameters of its own. To create an instance of `Innermost1`, call the method with an array containing three types, to be assigned to T, U, and V. To create an instance of `Innermost2`, call the method with an array containing two types, to be assigned to T and U. -The languages propagate the type parameters of enclosing types in this fashion so you can use the type parameters of an enclosing type to define fields of nested types. Otherwise, the type parameters would not be in scope within the bodies of the nested types. It is possible to define nested types without propagating the type parameters of enclosing types, by emitting code in dynamic assemblies or by using the [Ilasm.exe (IL Assembler)](../../framework/tools/ilasm-exe-il-assembler.md). Consider the following code for the MSIL assembler: +The languages propagate the type parameters of enclosing types in this fashion so you can use the type parameters of an enclosing type to define fields of nested types. Otherwise, the type parameters would not be in scope within the bodies of the nested types. It is possible to define nested types without propagating the type parameters of enclosing types, by emitting code in dynamic assemblies or by using the [Ilasm.exe (IL Assembler)](../../framework/tools/ilasm-exe-il-assembler.md). Consider the following code for the CIL assembler: ```msil .class public Outer { diff --git a/docs/fundamentals/runtime-libraries/system-xml-xmlresolver.md b/docs/fundamentals/runtime-libraries/system-xml-xmlresolver.md index 5c6a4dc63cedf..23412795efd2e 100644 --- a/docs/fundamentals/runtime-libraries/system-xml-xmlresolver.md +++ b/docs/fundamentals/runtime-libraries/system-xml-xmlresolver.md @@ -6,7 +6,7 @@ dev_langs: - CSharp - VB --- -# xref:System.Xml.XmlResolver> class +# class [!INCLUDE [context](includes/context.md)] diff --git a/docs/machine-learning/automate-training-with-cli.md b/docs/machine-learning/automate-training-with-cli.md index 1293fe86d8e08..443406b725844 100644 --- a/docs/machine-learning/automate-training-with-cli.md +++ b/docs/machine-learning/automate-training-with-cli.md @@ -14,11 +14,11 @@ To use the ML.NET API by itself, (without the ML.NET AutoML CLI) you need to cho The ML.NET CLI simplifies this process using automated machine learning (AutoML). > [!NOTE] -> This topic refers to ML.NET **CLI** and ML.NET **AutoML**, which are currently in Preview, and material may be subject to change. +> This article refers to ML.NET **CLI** and ML.NET **AutoML**, which are currently in Preview, and material may be subject to change. ## What is the ML.NET command-line interface (CLI)? -The ML.NET CLI is a [.NET Core tool](../core/tools/global-tools.md). Once installed, you give it a machine learning task and a training dataset, and it generates an ML.NET model, as well as the C# code to run to use the model in your application. +The ML.NET CLI is a [.NET tool](../core/tools/global-tools.md). Once installed, you give it a machine learning task and a training dataset, and it generates an ML.NET model, as well as the C# code to run to use the model in your application. As shown in the following figure, it is simple to generate a high quality ML.NET model (serialized model .zip file) plus the sample C# code to run/score that model. In addition, the C# code to create/train that model is also generated, so that you can research and iterate on the algorithm and settings used for that generated "best model". @@ -69,7 +69,7 @@ The ML task commands in the CLI generate the following assets in the output fold - C# code with the training code used to generate that model (for learning purposes or model retraining). - Log file with information of all iterations/sweeps across the multiple algorithms evaluated, including their detailed configuration/pipeline. -The first two assets can directly be used in your end-user apps (ASP.NET Core web app, services, desktop app, etc.) to make predictions with that generated ML model. +The first two assets can directly be used in your end-user apps (for example, ASP.NET Core web apps, services, and desktop apps) to make predictions with that generated ML model. The third asset, the training code, shows you what ML.NET API code was used by the CLI to train the generated model, so you can retrain your model and investigate and iterate on which specific trainer/algorithm and hyperparameters were selected by the CLI and AutoML under the covers. diff --git a/docs/machine-learning/automate-training-with-model-builder.md b/docs/machine-learning/automate-training-with-model-builder.md index 5171fc7870852..aa9fb0ff34272 100644 --- a/docs/machine-learning/automate-training-with-model-builder.md +++ b/docs/machine-learning/automate-training-with-model-builder.md @@ -3,25 +3,22 @@ title: What is Model Builder and how does it work? description: How to use the ML.NET Model Builder to automatically train a machine learning model ms.date: 11/10/2022 ms.custom: overview, mlnet-tooling +ms.topic: concept-article #Customer intent: As a developer, I want to use Model Builder to automatically train a model using a visual interface. --- # What is Model Builder and how does it work? -ML.NET Model Builder is an intuitive graphical Visual Studio extension to build, train, and deploy custom machine learning models. - -Model Builder uses automated machine learning (AutoML) to explore different machine learning algorithms and settings to help you find the one that best suits your scenario. +ML.NET Model Builder is an intuitive graphical Visual Studio extension to build, train, and deploy custom machine learning models. It uses automated machine learning (AutoML) to explore different machine learning algorithms and settings to help you find the one that best suits your scenario. You don't need machine learning expertise to use Model Builder. All you need is some data, and a problem to solve. Model Builder generates the code to add the model to your .NET application. :::image type="content" source="media/model-builder-scenarios-2-0.png" alt-text="Model Builder scenario screen" lightbox="media/model-builder-scenarios-2-0.png"::: -## Creating a Model Builder Project - -When you first start up Model Builder it will ask for you to name the project. This will create an `mbconfig` configuration file inside of the project. +## Create a Model Builder project -The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. +When you first start up Model Builder, it asks you to name the project, and then creates an `mbconfig` configuration file inside of the project. The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. -After training, three files are generated under the *.mbconfig file: +After training, three files are generated under the \*.mbconfig file: - **Model.consumption.cs:** This file contains the `ModelInput` and `ModelOutput` schemas as well as the `Predict` function generated for consuming the model. - **Model.training.cs:** This file contains the training pipeline (data transforms, algorithm, algorithm hyperparameters) chosen by Model Builder to train the model. You can use this pipeline for re-training your model. @@ -35,22 +32,22 @@ You can bring many different scenarios to Model Builder, to generate a machine l A scenario is a description of the type of prediction you want to make using your data. For example: -- predict future product sales volume based on historical sales data -- classify sentiments as positive or negative based on customer reviews -- detect whether a banking transaction is fraudulent -- route customer feedback issues to the correct team in your company +- Predict future product sales volume based on historical sales data. +- Classify sentiments as positive or negative based on customer reviews. +- Detect whether a banking transaction is fraudulent. +- Route customer feedback issues to the correct team in your company. -Each scenario maps to a different Machine Learning Task which include: +Each scenario maps to a different machine learning task, which include: -| Task | Scenario | -| --- | --- | -| Binary classification | Data classification | -| Multiclass classification | Data classification | -| Image classification | Image classification | -| Text classification | Text classification | -| Regression | Value prediction | -| Recommendation | Recommendation | -| Forecasting | Forecasting | +| Task | Scenario | +|---------------------------|----------------------| +| Binary classification | Data classification | +| Multiclass classification | Data classification | +| Image classification | Image classification | +| Text classification | Text classification | +| Regression | Value prediction | +| Recommendation | Recommendation | +| Forecasting | Forecasting | For example, the scenario of classifying sentiments as positive or negative would fall under the binary classification task. @@ -58,7 +55,7 @@ For more information about the different ML Tasks supported by ML.NET see [Machi ### Which machine learning scenario is right for me? -In Model Builder, you need to select a scenario. The type of scenario depends on what type of prediction you are trying to make. +In Model Builder, you need to select a scenario. The type of scenario depends on what type of prediction you're trying to make. #### Tabular @@ -172,7 +169,7 @@ You can use the forecasting scenario to forecast demand or sale for a product. :::column-end::: :::row-end::: -#### Computer Vision +#### Computer vision ##### Image classification @@ -201,7 +198,7 @@ You can use the image classification scenario if you have a set of images, and y ##### Object detection -Object detection is used to locate and categorize entities within images. For example, locating and identifying cars and people in an image. +Object detection is used to locate and categorize entities within images. For example, locating and identifying cars and people in an image. You can use object detection when images contain multiple objects of different types. @@ -222,7 +219,7 @@ You can use object detection when images contain multiple objects of different t :::column-end::: :::row-end::: -#### Natural Language Processing +#### Natural language processing ##### Text classification @@ -258,22 +255,22 @@ You can train your machine learning model locally on your machine or in the clou When you train locally, you work within the constraints of your computer resources (CPU, memory, and disk). When you train in the cloud, you can scale up your resources to meet the demands of your scenario, especially for large datasets. | Scenario | Local CPU | Local GPU | Azure | -|-----------------------|------------|------------|--------| -| Data classification | ✔️ | ❌ | ❌ | -| Value prediction | ✔️ | ❌ | ❌ | -| Recommendation | ✔️ | ❌ | ❌ | -| Forecasting | ✔️ | ❌ | ❌ | -| Image classification | ✔️ | ✔️ | ✔️ | -| Object detection | ❌ | ❌ | ✔️ | -| Text classification | ✔️ | ✔️ | ❌ | +|----------------------|-----------|-----------|-------| +| Data classification | ✔️ | ❌ | ❌ | +| Value prediction | ✔️ | ❌ | ❌ | +| Recommendation | ✔️ | ❌ | ❌ | +| Forecasting | ✔️ | ❌ | ❌ | +| Image classification | ✔️ | ✔️ | ✔️ | +| Object detection | ❌ | ❌ | ✔️ | +| Text classification | ✔️ | ✔️ | ❌ | ## Data -Once you have chosen your scenario, Model Builder asks you to provide a dataset. The data is used to train, evaluate, and choose the best model for your scenario. +Once you've chosen your scenario, Model Builder asks you to provide a dataset. The data is used to train, evaluate, and choose the best model for your scenario. ![Diagram showing Model Builder steps](media/model-builder-steps.png) -Model Builder supports datasets in .tsv, .csv, .txt formats, as well as SQL database format. If you have a .txt file, columns should be separated with `,`, `;` or `\t`. +Model Builder supports datasets in .tsv, .csv, .txt, and SQL database formats. If you have a .txt file, columns should be separated with `,`, `;`, or `\t`. If the dataset is made up of images, the supported file types are `.jpg` and `.png`. @@ -284,13 +281,13 @@ For more information, see [Load training data into Model Builder](how-to-guides/ A dataset is a table of rows of training examples, and columns of attributes. Each row has: - a **label** (the attribute that you want to predict) -- **features** (attributes that are used as inputs to predict the label). +- **features** (attributes that are used as inputs to predict the label) For the house-price prediction scenario, the features could be: -- the square footage of the house -- the number of bedrooms and bathrooms -- the zip code +- The square footage of the house. +- The number of bedrooms and bathrooms. +- The zip code. The label is the historical house price for that row of square footage, bedroom, and bathroom values and zip code. @@ -300,8 +297,8 @@ The label is the historical house price for that row of square footage, bedroom, If you don't have your own data yet, try out one of these datasets: -|Scenario|Example|Data|Label|Features| -|-|-|-|-|-| +| Scenario | Example | Data | Label | Features | +|----------|---------|------|-------|----------| |Classification|Predict sales anomalies|[product sales data](https://github.com/dotnet/machinelearning-samples/blob/main/samples/csharp/getting-started/AnomalyDetection_Sales/SpikeDetection/Data/product-sales.csv)|Product Sales|Month| ||Predict sentiment of website comments|[website comment data](https://raw.githubusercontent.com/dotnet/machinelearning/main/test/data/wikipedia-detox-250-line-data.tsv)|Label (0 when negative sentiment, 1 when positive)|Comment, Year| ||Predict fraudulent credit card transactions|[credit card data](https://github.com/dotnet/machinelearning-samples/blob/main/samples/csharp/getting-started/BinaryClassification_CreditCardFraudDetection/CCFraudDetection.Trainer/assets/input/creditcardfraud-dataset.zip)|Class (1 when fraudulent, 0 otherwise)|Amount, V1-V28 (anonymized features)| @@ -328,20 +325,20 @@ Longer training periods allow AutoML to explore more models with a wider range o The table below summarizes the average time taken to get good performance for a suite of example datasets, on a local machine. -|Dataset size|Average time to train| -|------------|---------------------| -|0 - 10 MB|10 sec| -|10 - 100 MB|10 min| -|100 - 500 MB|30 min| -|500 - 1 GB|60 min| -|1 GB+|3+ hours| +| Dataset size | Average time to train | +|--------------|-----------------------| +| 0 - 10 MB | 10 sec | +| 10 - 100 MB | 10 min | +| 100 - 500 MB | 30 min | +| 500 - 1 GB | 60 min | +| 1 GB+ | 3+ hours | These numbers are a guide only. The exact length of training is dependent on: -- the number of features (columns) being used to as input to the model -- the type of columns -- the ML task -- the CPU, disk, and memory performance of the machine used for training +- The number of features (columns) being used to as input to the model. +- The type of columns. +- The ML task. +- The CPU, disk, and memory performance of the machine used for training. It's generally advised that you use more than 100 rows as datasets with less than that may not produce any results. @@ -398,11 +395,11 @@ After the evaluation phase, Model Builder outputs a model file, and code that yo In addition, Model Builder gives you the option to create projects that consume your model. Currently, Model Builder will create the following projects: -- **Console app:** Creates a .NET Core console applications to make predictions from your model. +- **Console app:** Creates a .NET console application to make predictions from your model. - **Web API:** Creates an ASP.NET Core Web API that lets you consume your model over the internet. ## What's next? -[Install](how-to-guides/install-model-builder.md) the Model Builder Visual Studio extension +[Install](how-to-guides/install-model-builder.md) the Model Builder Visual Studio extension. -Try [price prediction or any regression scenario](tutorials/predict-prices-with-model-builder.md) +Try [price prediction or any regression scenario](tutorials/predict-prices-with-model-builder.md). diff --git a/docs/machine-learning/automated-machine-learning-mlnet.md b/docs/machine-learning/automated-machine-learning-mlnet.md index 7c18ab2a54b20..39c2264363659 100644 --- a/docs/machine-learning/automated-machine-learning-mlnet.md +++ b/docs/machine-learning/automated-machine-learning-mlnet.md @@ -11,7 +11,7 @@ ms.custom: mvc Automated machine learning (AutoML) automates the process of applying machine learning to data. Given a dataset, you can run AutoML to iterate over different data transformations, machine learning algorithms, and hyperparameters to select the best model. > [!NOTE] -> This topic refers to the ML.NET AutoML API, which is currently in preview. Material may be subject to change. +> This article refers to the ML.NET AutoML API, which is currently in preview. Material may be subject to change. ## How does AutoML work? @@ -31,8 +31,8 @@ Preprocessing, training, and evaluation are an experimental and iterative proces Whether you're just getting started with machine learning or you're an experienced user, AutoML provides solutions for automating the model development process. -- **Beginners** - If you're new to machine learning, AutoML simplifies the model development process by providing a set of defaults that reduces the number of decisions you have to make when training your model. In doing so, you can focus on your data and the problem you're trying to solve and let AutoML do the rest. -- **Experienced users** - If you have some experience with machine learning, you can customize, configure, and extend the defaults provided by AutoML based on your needs while still leveraging its automation capabilities. +- **Beginners** - If you're new to machine learning, AutoML simplifies the model development process by providing a set of defaults that reduces the number of decisions you have to make when training your model. In doing so, you can focus on your data and the problem you're trying to solve and let AutoML do the rest. +- **Experienced users** - If you have some experience with machine learning, you can customize, configure, and extend the defaults provided by AutoML based on your needs while still leveraging its automation capabilities. ## AutoML in ML.NET @@ -48,7 +48,7 @@ Whether you're just getting started with machine learning or you're an experienc - **Random Search** - **Sweepable Estimator** - An ML.NET estimator that contains a search space. - **Sweepable Pipeline** - An ML.NET pipeline that contains one or more Sweepable Estimators. -- **Trial Runner** - AutoML component that uses sweepable pipelines and trial settings to generate trial results from model training and evaluation. +- **Trial Runner** - AutoML component that uses sweepable pipelines and trial settings to generate trial results from model training and evaluation. It's recommended for beginners to start with the defaults provided by the high-level experiment API. For more experienced users looking for customization options, use the sweepable estimator, sweepable pipeline, search space, trial runner and tuner components. @@ -62,7 +62,7 @@ AutoML provides preconfigured defaults for the following tasks: - Multiclass classification - Regression -For other tasks, you can build your own trial runner to enable those scenarios. For more information, see the [How to use the ML.NET Automated Machine Learning (AutoML) API](how-to-guides/how-to-use-the-automl-api.md) guide. +For other tasks, you can build your own trial runner to enable those scenarios. For more information, see the [How to use the ML.NET Automated Machine Learning (AutoML) API](how-to-guides/how-to-use-the-automl-api.md) guide. ## Next steps diff --git a/docs/machine-learning/deep-learning-overview.md b/docs/machine-learning/deep-learning-overview.md index 6e1f2068d055d..0bb41c95831c8 100644 --- a/docs/machine-learning/deep-learning-overview.md +++ b/docs/machine-learning/deep-learning-overview.md @@ -1,6 +1,6 @@ --- title: Deep Learning overview -description: Learn what deep learning is and components in ML.NET +description: Learn what deep learning is and components in ML.NET ms.date: 11/10/2022 ms.topic: overview ms.custom: mvc @@ -8,25 +8,25 @@ ms.custom: mvc # What is deep learning? -Deep learning is an umbrella term for machine learning techniques that make use of "deep" neural networks. Today, deep learning is one of the most visible areas of machine learning because of its success in areas like Computer Vision, Natural Language Processing, and when applied to reinforcement learning, scenarios like game playing, decision making and simulation. +Deep learning is an umbrella term for machine-learning techniques that make use of "deep" neural networks. Today, deep learning is one of the most visible areas of machine learning because of its success in areas like computer vision, natural language processing, and—when applied to reinforcement learning—scenarios like game playing, decision making, and simulation. -A crucial element to the success of deep learning has been the availability of data, compute, software frameworks, and runtimes that facilitate the creation of neural network models and their execution for inference. Examples of such frameworks include TensorFlow, (Py)Torch and ONNX. +A crucial element to the success of deep learning has been the availability of data, compute, software frameworks, and runtimes that facilitate the creation of neural network models and their execution for inference. Examples of such frameworks include TensorFlow, (Py)Torch, and ONNX. ML.NET provides access to some of these frameworks. As a result, ML.NET users can take advantage of deep learning models without having to start from scratch. -## Deep Learning vs Machine Learning? +## Deep learning vs machine learning -Deep learning relies on neural network algorithms. This is in contrast with traditional or classical machine learning techniques which use a wider variety of algorithms such as generalized linear models, decision trees or Support Vector Machines (SVM). The most immediate, practical implication of this difference is that deep learning methods may be better suited for some kind of data. In some cases, classical machine learning techniques such as gradient-boosted trees (XGBoost, LightGBM and CatBoost) seem to have an edge for tabular data. For less structured data like text and images, neural networks tend to perform better. The best approach is always to experiment with your particular data source and use case to determine for yourself which techniques work best for your problem. +Deep learning relies on neural network algorithms. This is in contrast with traditional or classical machine learning techniques which use a wider variety of algorithms such as generalized linear models, decision trees or Support Vector Machines (SVM). The most immediate, practical implication of this difference is that deep learning methods may be better suited for some kind of data. In some cases, classical machine learning techniques such as gradient-boosted trees (XGBoost, LightGBM and CatBoost) seem to have an edge for tabular data. For less structured data like text and images, neural networks tend to perform better. The best approach is always to experiment with your particular data source and use case to determine for yourself which techniques work best for your problem. For classical machine learning tasks, ML.NET simplifies this experimentation process through Automated Machine Learning (AutoML). For more information on AutoML, see the article [what is Automated Machine Learning (AutoML)?](automated-machine-learning-mlnet.md). -## Neural Network architectures +## Neural network architectures -One of the main differentiating characteristics of deep learning is the use of artificial neural network algorithms. At a high-level, you can think of neural networks as a configuration of "processing units" where the output of each unit constitutes the input of another. Each of these units can take one or many inputs, and essentially carries out a weighted sum of its inputs, applies an offset (or "bias") and then a non-linear transformation function (called "activation"). Different arrangements of these components have been used to describe decision boundaries in classification, regression functions and other structures central to machine learning tasks. +One of the main differentiating characteristics of deep learning is the use of artificial neural network algorithms. At a high-level, you can think of neural networks as a configuration of "processing units" where the output of each unit constitutes the input of another. Each of these units can take one or many inputs, and essentially carries out a weighted sum of its inputs, applies an offset (or "bias") and then a non-linear transformation function (called "activation"). Different arrangements of these components have been used to describe decision boundaries in classification, regression functions and other structures central to machine learning tasks. :::image type="content" source="media/single-layer-neural-net.png" alt-text="Diagram representing single layer in neural network" lightbox="media/single-layer-neural-net.png"::: -The past decade has seen an increase in cases, applications and techniques of deep learning. This increase is driven in part by an increasing variety of operations that can be incorporated into neural networks, a richer set of arrangements that these operations can be configured in and improved computational support for these improvements. In general, neural network architectures can be grouped into the following categories: +The past decade has seen an increase in cases, applications and techniques of deep learning. This increase is driven in part by an increasing variety of operations that can be incorporated into neural networks, a richer set of arrangements that these operations can be configured in and improved computational support for these improvements. In general, neural network architectures can be grouped into the following categories: * Feed-forward Neural Network * Convolutional Neural Network @@ -38,7 +38,7 @@ For more details, see the [artificial neural networks guide](/azure/machine-lear ## What can I use deep learning for? -Deep learning architectures, have shown good performance in tasks involving "unstructured data" such as images, audio, and free-form text. As a result, deep learning has been used to solve problems like: +Deep learning architectures, have shown good performance in tasks involving "unstructured data" such as images, audio, and free-form text. As a result, deep learning has been used to solve problems like: * Image classification * Audio classification @@ -91,7 +91,7 @@ At this time, there is no local support for object detection in ML.NET. To train custom object detection models with ML.NET, see the [Detect stop signs in images with Model Builder tutorial](tutorials/object-detection-model-builder.md) -#### Text classification +#### Text classification Classifying free-form text, whether that's customer reviews or business memos is an important part of many processes. @@ -101,7 +101,7 @@ A text classification training pipeline in ML.NET might look like the following: ```csharp // Define training pipeline using TextClassification trainer -var pipeline = +var pipeline = mlContext.Transforms.Conversion.MapValueToKey("Label","Sentiment") .Append(mlContext.MulticlassClassification.Trainers.TextClassification(sentence1ColumnName: "Text")) .Append(mlContext.Transforms.Conversion.MapKeyToValue("PredictedLabel")); @@ -115,7 +115,7 @@ var predictedData = model.Transform(newData).GetColumn("PredictedLabel") To get started training text classification models with ML.NET, see the [Analyze sentiment of website comments in a web application using ML.NET Model Builder tutorial](tutorials/sentiment-analysis-model-builder.md). -#### Sentence Similarity +#### Sentence similarity Tasks such as semantic search rely on the determination of how similar two sentences or passages of text are to each other. @@ -142,9 +142,9 @@ ML.NET provides APIs to consume models in other formats like TensorFlow and ONNX These APIs are powered by [TensorFlow.NET](https://github.com/SciSharp/TensorFlow.NET) and the [ONNX Runtime](https://onnxruntime.ai/). -#### TensorFlow +#### TensorFlow -[TensorFlow](https://www.tensorflow.org/) is a deep learning framework with a rich ecosystem and a variety of pre-trained models available in the [TensorFlow Hub](https://www.tensorflow.org/hub). +[TensorFlow](https://www.tensorflow.org/) is a deep learning framework with a rich ecosystem and a variety of pre-trained models available in the [TensorFlow Hub](https://www.tensorflow.org/hub). With ML.NET, you can take these pretrained TensorFlow models and use them for inferencing inside your .NET applications. @@ -165,11 +165,11 @@ var predictions = model.Transform(dataView).GetColumn("Prediction/Softmax To get started consuming pretrained TensorFlow models with ML.NET, see the [movie reviews sentiment analysis using a pre-trained TensorFlow model in ML.NET tutorial](tutorials/text-classification-tf.md) -#### ONNX +#### ONNX -The [Open Neural Network Exchange(ONNX)](https://onnx.ai/) is an open-source format designed to enable interoperability between machine learning and deep learning frameworks. This means you can train a model in one of the many popular machine learning frameworks like PyTorch, convert it into ONNX format and consume the ONNX model in a different framework like ML.NET. +The [Open Neural Network Exchange (ONNX)](https://onnx.ai/) is an open-source format designed to enable interoperability between machine-learning and deep-learning frameworks. This means you can train a model in one of the many popular machine-learning frameworks like PyTorch, convert it into ONNX format, and consume the ONNX model in a different framework like ML.NET. -The [ONNX model repository](https://github.com/onnx/models) hosts several pre-trained ONNX models you can use for inferencing in a wide variety of tasks. +The [ONNX model repository](https://github.com/onnx/models) hosts several pretrained ONNX models you can use for inferencing in a wide variety of tasks. With ML.NET, you can take these pretrained ONNX models and use them for inferencing inside your .NET applications. @@ -186,4 +186,4 @@ var model = pipeline.Fit(data); var predictions = pipeline.Fit(data).GetColumn(TinyYoloModelSettings.ModelOutput); ``` -To get started consuming pretrained ONNX models with ML.NET, see the [object detection using ONNX in ML.NET tutorial](tutorials/object-detection-onnx.md) +To get started consuming pretrained ONNX models with ML.NET, see the [object detection using ONNX in ML.NET](tutorials/object-detection-onnx.md) tutorial. diff --git a/docs/machine-learning/how-does-mldotnet-work.md b/docs/machine-learning/how-does-mldotnet-work.md index b0d03280893be..07745f04d8ad2 100644 --- a/docs/machine-learning/how-does-mldotnet-work.md +++ b/docs/machine-learning/how-does-mldotnet-work.md @@ -15,74 +15,20 @@ Central to ML.NET is a machine learning **model**. The model specifies the steps Once you have a model, you can add it to your application to make the predictions. -ML.NET runs on Windows, Linux, and macOS using .NET Core, or Windows using .NET Framework. 64 bit is supported on all platforms. 32 bit is supported on Windows, except for TensorFlow, LightGBM, and ONNX-related functionality. - -Examples of the type of predictions that you can make with ML.NET: - -:::row::: - :::column::: - **Classification/Categorization** - :::column-end::: - :::column::: - Automatically divide customer feedback into positive and negative categories - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Regression/Predict continuous values** - :::column-end::: - :::column::: - Predict the price of houses based on size and location - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Anomaly Detection** - :::column-end::: - :::column::: - Detect fraudulent banking transactions - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Recommendations** - :::column-end::: - :::column::: - Suggest products that online shoppers may want to buy, based on their previous purchases - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Time series/sequential data** - :::column-end::: - :::column::: - Forecast the weather/product sales - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Image classification** - :::column-end::: - :::column::: - Categorize pathologies in medical images - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Text classification** - :::column-end::: - :::column::: - Categorize documents based on their content. - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Sentence similarity** - :::column-end::: - :::column::: - Measure how similar two sentences are. - :::column-end::: -:::row-end::: +ML.NET runs on Windows, Linux, and macOS using .NET, or on Windows using .NET Framework. 64 bit is supported on all platforms. 32 bit is supported on Windows, except for TensorFlow, LightGBM, and ONNX-related functionality. + +The following table shows examples of the type of predictions that you can make with ML.NET. + +| Prediction type | Example | +|--------------------------------------|-------------------------------------------------------------------------------------------| +| Classification/Categorization | Automatically divide customer feedback into positive and negative categories. | +| Regression/Predict continuous values | Predict the price of houses based on size and location. | +| Anomaly Detection | Detect fraudulent banking transactions. | +| Recommendations | Suggest products that online shoppers may want to buy, based on their previous purchases. | +| Time series/sequential data | Forecast the weather or product sales. | +| Image classification | Categorize pathologies in medical images. | +| Text classification | Categorize documents based on their content. | +| Sentence similarity | Measure how similar two sentences are. | ## Hello ML.NET World @@ -218,164 +164,71 @@ The evaluation metrics tell you that the error is low-ish, and that correlation ## ML.NET architecture -In this section, we go through the architectural patterns of ML.NET. If you are an experienced .NET developer, some of these patterns will be familiar to you, and some will be less familiar. Hold tight, while we dive in! - -An ML.NET application starts with an object. This singleton object contains **catalogs**. A catalog is a factory for data loading and saving, transforms, trainers, and model operation components. Each catalog object has methods to create the different types of components: - -:::row::: - :::column::: - **Data loading and saving** - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Data preparation** - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column span="3"::: - **Training algorithms** - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Binary classification - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Multiclass classification - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Anomaly detection - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Clustering - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Forecasting - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Ranking - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Regression - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: -:::row::: - :::column::: - Recommendation - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span=""::: - Add the `Microsoft.ML.Recommender` NuGet package - :::column-end::: -:::row-end::: -:::row::: - :::column::: - TimeSeries - :::column-end::: - :::column span=""::: - - :::column-end::: - :::column span=""::: - Add the `Microsoft.ML.TimeSeries` NuGet package - :::column-end::: -:::row-end::: -:::row::: - :::column::: - **Model usage** - :::column-end::: - :::column span="2"::: - - :::column-end::: -:::row-end::: +This section describes the architectural patterns of ML.NET. If you're an experienced .NET developer, some of these patterns will be familiar to you, and some will be less familiar. + +An ML.NET application starts with an object. This singleton object contains **catalogs**. A catalog is a factory for data loading and saving, transforms, trainers, and model operation components. Each catalog object has methods to create the different types of components. + +| Task | Catalog | +|---------------------------|-----------------------------------------------------| +| Data loading and saving | | +| Data preparation | | +| Binary classification | | +| Multiclass classification | | +| Anomaly detection | | +| Clustering | | +| Forecasting | | +| Ranking | | +| Regression | | +| Recommendation | | +| Time series | | +| Model usage | | You can navigate to the creation methods in each of the above categories. Using Visual Studio, the catalogs show up via IntelliSense. - ![Intellisense for Regression Trainers](./media/catalog-intellisense.png) +![Intellisense for Regression Trainers](./media/catalog-intellisense.png) ### Build the pipeline -Inside each catalog is a set of extension methods. Let's look at how extension methods are used to create a training pipeline. +Inside each catalog is a set of extension methods that you can use to create a training pipeline. ```csharp - var pipeline = mlContext.Transforms.Concatenate("Features", new[] { "Size" }) - .Append(mlContext.Regression.Trainers.Sdca(labelColumnName: "Price", maximumNumberOfIterations: 100)); +var pipeline = mlContext.Transforms.Concatenate("Features", new[] { "Size" }) + .Append(mlContext.Regression.Trainers.Sdca(labelColumnName: "Price", maximumNumberOfIterations: 100)); ``` -In the snippet, `Concatenate` and `Sdca` are both methods in the catalog. They each create an [IEstimator](xref:Microsoft.ML.IEstimator%601) object that is appended to the pipeline. +In the snippet, `Concatenate` and `Sdca` are both methods in the catalog. They each create an [IEstimator](xref:Microsoft.ML.IEstimator%601) object that's appended to the pipeline. -At this point, the objects are created only. No execution has happened. +At this point, the objects have been created, but no execution has happened. ### Train the model Once the objects in the pipeline have been created, data can be used to train the model. ```csharp - var model = pipeline.Fit(trainingData); +var model = pipeline.Fit(trainingData); ``` -Calling `Fit()` uses the input training data to estimate the parameters of the model. This is known as training the model. Remember, the linear regression model above had two model parameters: **bias** and **weight**. After the `Fit()` call, the values of the parameters are known. Most models will have many more parameters than this. +Calling `Fit()` uses the input training data to estimate the parameters of the model. This is known as training the model. Remember, the linear regression model shown earlier had two model parameters: **bias** and **weight**. After the `Fit()` call, the values of the parameters are known. (Most models will have many more parameters than this.) You can learn more about model training in [How to train your model](./how-to-guides/train-machine-learning-model-ml-net.md). The resulting model object implements the interface. That is, the model transforms input data into predictions. ```csharp - IDataView predictions = model.Transform(inputData); +IDataView predictions = model.Transform(inputData); ``` ### Use the model -You can transform input data into predictions in bulk, or one input at a time. In the house price example, we did both: in bulk for the purpose of evaluating the model, and one at a time to make a new prediction. Let's look at making single predictions. +You can transform input data into predictions in bulk, or one input at a time. The house price example did both: in bulk for the purpose of evaluating the model, and one at a time to make a new prediction. Let's look at making single predictions. ```csharp - var size = new HouseData() { Size = 2.5F }; - var predEngine = mlContext.CreatePredictionEngine(model); - var price = predEngine.Predict(size); +var size = new HouseData() { Size = 2.5F }; +var predEngine = mlContext.CreatePredictionEngine(model); +var price = predEngine.Predict(size); ``` -The `CreatePredictionEngine()` method takes an input class and an output class. The field names and/or code attributes determine the names of the data columns used during model training and prediction. For more information, see [Make predictions with a trained model](how-to-guides/machine-learning-model-predictions-ml-net.md). +The `CreatePredictionEngine()` method takes an input class and an output class. The field names or code attributes determine the names of the data columns used during model training and prediction. For more information, see [Make predictions with a trained model](how-to-guides/machine-learning-model-predictions-ml-net.md). ### Data models and schema @@ -387,40 +240,40 @@ If the output schema from one transform in the pipeline doesn't match the input A data view object has columns and rows. Each column has a name and a type and a length. For example, the input columns in the house price example are **Size** and **Price**. They are both type and they are scalar quantities rather than vector ones. - ![ML.NET Data View example with house price prediction data](./media/ml-net-dataview.png) +![ML.NET Data View example with house price prediction data](./media/ml-net-dataview.png) -All ML.NET algorithms look for an input column that is a vector. By default this vector column is called **Features**. This is why we concatenated the **Size** column into a new column called **Features** in our house price example. +All ML.NET algorithms look for an input column that's a vector. By default, this vector column is called **Features**. That's why the house price example concatenated the **Size** column into a new column called **Features**. ```csharp - var pipeline = mlContext.Transforms.Concatenate("Features", new[] { "Size" }) +var pipeline = mlContext.Transforms.Concatenate("Features", new[] { "Size" }) ``` -All algorithms also create new columns after they have performed a prediction. The fixed names of these new columns depend on the type of machine learning algorithm. For the regression task, one of the new columns is called **Score**. This is why we attributed our price data with this name. +All algorithms also create new columns after they've performed a prediction. The fixed names of these new columns depend on the type of machine learning algorithm. For the regression task, one of the new columns is called **Score** as shown in the price data attribute. ```csharp - public class Prediction - { - [ColumnName("Score")] - public float Price { get; set; } - } +public class Prediction +{ + [ColumnName("Score")] + public float Price { get; set; } +} ``` You can find out more about output columns of different machine learning tasks in the [Machine Learning Tasks](resources/tasks.md) guide. -An important property of DataView objects is that they are evaluated **lazily**. Data views are only loaded and operated on during model training and evaluation, and data prediction. While you are writing and testing your ML.NET application, you can use the Visual Studio debugger to take a peek at any data view object by calling the [Preview](xref:Microsoft.ML.DebuggerExtensions.Preview%2A) method. +An important property of DataView objects is that they're evaluated **lazily**. Data views are only loaded and operated on during model training and evaluation, and data prediction. While you are writing and testing your ML.NET application, you can use the Visual Studio debugger to take a peek at any data view object by calling the [Preview](xref:Microsoft.ML.DebuggerExtensions.Preview%2A) method. ```csharp - var debug = testPriceDataView.Preview(); +var debug = testPriceDataView.Preview(); ``` You can watch the `debug` variable in the debugger and examine its contents. Do not use the Preview method in production code, as it significantly degrades performance. -### Model Deployment +### Model deployment In real-life applications, your model training and evaluation code will be separate from your prediction. In fact, these two activities are often performed by separate teams. Your model development team can save the model for use in the prediction application. ```csharp - mlContext.Model.Save(model, trainingData.Schema,"model.zip"); +mlContext.Model.Save(model, trainingData.Schema,"model.zip"); ``` ## Next steps diff --git a/docs/machine-learning/how-to-guides/install-extra-dependencies.md b/docs/machine-learning/how-to-guides/install-extra-dependencies.md index 20dc1e02c2e01..6f6d331336cc8 100644 --- a/docs/machine-learning/how-to-guides/install-extra-dependencies.md +++ b/docs/machine-learning/how-to-guides/install-extra-dependencies.md @@ -32,7 +32,7 @@ No extra installation steps required. The library is installed when the NuGet pa ```bash sudo bash - # + # # cd to /tmp where this shell has write permission cd /tmp # now get the key: @@ -88,8 +88,8 @@ No extra installation steps required. The library is installed when the NuGet pa ### Mac -1. Install the library with `Homebrew` +Install the library with `Homebrew` - ```bash - wget https://raw.githubusercontent.com/Homebrew/homebrew-core/fb8323f2b170bd4ae97e1bac9bf3e2983af3fdb0/Formula/libomp.rb && brew install ./libomp.rb && brew link libomp --force - ``` +```bash +wget https://raw.githubusercontent.com/Homebrew/homebrew-core/fb8323f2b170bd4ae97e1bac9bf3e2983af3fdb0/Formula/libomp.rb && brew install ./libomp.rb && brew link libomp --force +``` diff --git a/docs/machine-learning/how-to-guides/install-ml-net-cli.md b/docs/machine-learning/how-to-guides/install-ml-net-cli.md index df24fbe289e83..b96f2795cc92a 100644 --- a/docs/machine-learning/how-to-guides/install-ml-net-cli.md +++ b/docs/machine-learning/how-to-guides/install-ml-net-cli.md @@ -13,7 +13,7 @@ Learn how to install the ML.NET CLI (command-line interface) on Windows, Mac, or The ML.NET CLI generates good quality ML.NET models and source code using automated machine learning (AutoML) and a training dataset. > [!NOTE] -> This topic refers to ML.NET CLI and ML.NET AutoML, which are currently in Preview, and material may be subject to change. +> This article refers to ML.NET CLI and ML.NET AutoML, which are currently in Preview, and material may be subject to change. ## Pre-requisites @@ -98,7 +98,7 @@ mlnet You should see the help for available commands for the mlnet tool such as the 'classification' command. > [!IMPORTANT] -> If you're running Linux or macOS and using a console other than Bash (for example, zsh, which is the new default for macOS), then you'll need to give `mlnet` executable permissions and include `mlnet` to the system path. In general, you can do so with the following command: +> If you're running Linux or macOS and using a console other than Bash (for example, zsh, which is the new default for macOS), then you'll need to give `mlnet` executable permissions and include `mlnet` to the system path. In general, you can do so with the following command: > > ```console > chmod +x diff --git a/docs/machine-learning/how-to-guides/load-data-ml-net.md b/docs/machine-learning/how-to-guides/load-data-ml-net.md index a47300d983659..f534497f6d0dd 100644 --- a/docs/machine-learning/how-to-guides/load-data-ml-net.md +++ b/docs/machine-learning/how-to-guides/load-data-ml-net.md @@ -43,7 +43,7 @@ public class HousingData } ``` -### Annotating the data model with column attributes +### Annotate the data model with column attributes Attributes give ML.NET more information about the data model and the data source. diff --git a/docs/machine-learning/how-to-guides/matchup-app-infer-net.md b/docs/machine-learning/how-to-guides/matchup-app-infer-net.md index 6608a9d33002b..f1e0d3b232d6a 100644 --- a/docs/machine-learning/how-to-guides/matchup-app-infer-net.md +++ b/docs/machine-learning/how-to-guides/matchup-app-infer-net.md @@ -16,13 +16,13 @@ Probabilistic programming allows you to create statistical models of real-world ## Prerequisites -- Local development environment setup +- Local development environment. This how-to guide expects you to have a machine you can use for development. The .NET tutorial [Hello World in 10 minutes](https://dotnet.microsoft.com/learn/dotnet/hello-world-tutorial/intro) has instructions for setting up your local development environment on macOS, Windows, or Linux. ## Create your app -1. Open a new command prompt and run the following commands: +Open a new command prompt and run the following commands: ```dotnetcli dotnet new console -o myApp @@ -41,20 +41,20 @@ dotnet add package Microsoft.ML.Probabilistic.Compiler ## Design your model -The example sample uses table tennis or foosball matches played in the office. You have the participants and outcome of each match. You want to infer the player's skills from this data. Assume that each player has a normally distributed latent skill and their given match performance is a noisy version of this skill. The data constrains the winner’s performance to be greater than the loser’s performance. This is a simplified version of the popular [TrueSkill](https://www.microsoft.com/research/project/trueskill-ranking-system/) model, which also supports teams, draws, and other extensions. An [advanced version](https://www.microsoft.com/research/publication/trueskill-2-improved-bayesian-skill-rating-system/) of this model is used for matchmaking in the best-selling game titles Halo and Gears of War. +The example sample uses table tennis or foosball matches played in the office. You have the participants and outcome of each match. You want to infer the player's skills from this data. Assume that each player has a normally distributed latent skill and their given match performance is a noisy version of this skill. The data constrains the winner’s performance to be greater than the loser’s performance. This is a simplified version of the popular [TrueSkill](https://www.microsoft.com/research/project/trueskill-ranking-system/) model, which also supports teams, draws, and other extensions. An [advanced version](https://www.microsoft.com/research/publication/trueskill-2-improved-bayesian-skill-rating-system/) of this model is used for matchmaking in the best-selling game titles Halo and Gears of War. You need to list the inferred player skills, alongside with their variance – the measure of uncertainty around the skills. *Game result sample data* -Game |Winner | Loser ----------|----------|--------- - 1 | Player 0 | Player 1 - 2 | Player 0 | Player 3 - 3 | Player 0 | Player 4 - 4 | Player 1 | Player 2 - 5 | Player 3 | Player 1 - 6 | Player 4 | Player 2 +| Game | Winner | Loser | +|------|----------|----------| +| 1 | Player 0 | Player 1 | +| 2 | Player 0 | Player 3 | +| 3 | Player 0 | Player 4 | +| 4 | Player 1 | Player 2 | +| 5 | Player 3 | Player 1 | +| 6 | Player 4 | Player 2 | With a closer look at the sample data, you’ll notice that players 3 and 4 both have one win and one loss. Let's see what the rankings look like using probabilistic programming. Notice also there is a player zero because even office match up lists are zero based to us developers. diff --git a/docs/machine-learning/how-to-guides/retrain-model-ml-net.md b/docs/machine-learning/how-to-guides/retrain-model-ml-net.md index 64dd5b091001f..cfba8b5c7985c 100644 --- a/docs/machine-learning/how-to-guides/retrain-model-ml-net.md +++ b/docs/machine-learning/how-to-guides/retrain-model-ml-net.md @@ -1,6 +1,6 @@ --- -title: Re-train a model -description: Learn how retrain a model in ML.NET +title: Retrain a model +description: Learn how to retrain a model in ML.NET ms.date: 11/02/2021 author: luisquintanilla ms.author: luquinta @@ -9,13 +9,13 @@ ms.topic: how-to #Customer intent: As a developer, I want to retrain a model using existing model parameters. --- -# Re-train a model +# Retrain a model Learn how to retrain a machine learning model in ML.NET. -The world and the data around it change at a constant pace. As such, models need to change and update as well. ML.NET provides functionality for re-training models using learned model parameters as a starting point to continually build on previous experience rather than starting from scratch every time. +The world and its data change constantly. As such, models need to change and update as well. ML.NET provides functionality for retraining models using learned model parameters as a starting point to continually build on previous experience rather than starting from scratch every time. -The following algorithms are re-trainable in ML.NET: +The following algorithms are retrainable in ML.NET: - [AveragedPerceptronTrainer](xref:Microsoft.ML.Trainers.AveragedPerceptronTrainer) - [FieldAwareFactorizationMachineTrainer](xref:Microsoft.ML.Trainers.FieldAwareFactorizationMachineTrainer) @@ -28,9 +28,9 @@ The following algorithms are re-trainable in ML.NET: - [SgdNonCalibratedTrainer](xref:Microsoft.ML.Trainers.SgdNonCalibratedTrainer) - [SymbolicSgdLogisticRegressionBinaryTrainer](xref:Microsoft.ML.Trainers.SymbolicSgdLogisticRegressionBinaryTrainer) -## Load pre-trained model +## Load pretrained model -First, load the pre-trained model into your application. To learn more about loading training pipelines and models, see [Save and load a trained model](save-load-machine-learning-models-ml-net.md). +First, load the pretrained model into your application. To learn more about loading training pipelines and models, see [Save and load a trained model](save-load-machine-learning-models-ml-net.md). ```csharp // Create MLContext @@ -46,9 +46,9 @@ ITransformer dataPrepPipeline = mlContext.Model.Load("data_preparation_pipeline. ITransformer trainedModel = mlContext.Model.Load("ogd_model.zip", out modelSchema); ``` -## Extract pre-trained model parameters +## Extract pretrained model parameters -Once the model is loaded, extract the learned model parameters by accessing the [`Model`](xref:Microsoft.ML.Data.PredictionTransformerBase%601.Model%2A) property of the pre-trained model. The pre-trained model was trained using the linear regression model [`OnlineGradientDescentTrainer`](xref:Microsoft.ML.Trainers.OnlineGradientDescentTrainer) which creates a [`RegressionPredictionTransformer`](xref:Microsoft.ML.Data.RegressionPredictionTransformer%601) that outputs [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters). These model parameters contain the learned bias and weights or coefficients of the model. These values will be used as a starting point for the new re-trained model. +Once the model is loaded, extract the learned model parameters by accessing the [`Model`](xref:Microsoft.ML.Data.PredictionTransformerBase%601.Model%2A) property of the pretrained model. The pretrained model was trained using the linear regression model [`OnlineGradientDescentTrainer`](xref:Microsoft.ML.Trainers.OnlineGradientDescentTrainer), which creates a [`RegressionPredictionTransformer`](xref:Microsoft.ML.Data.RegressionPredictionTransformer%601) that outputs [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters). These model parameters contain the learned bias and weights or coefficients of the model. These values are used as a starting point for the new retrained model. ```csharp // Extract trained model parameters @@ -59,9 +59,9 @@ LinearRegressionModelParameters originalModelParameters = > [!NOTE] > The model parameters output depend on the algorithm used. For example [`OnlineGradientDescentTrainer`](xref:Microsoft.ML.Trainers.OnlineGradientDescentTrainer) uses [`LinearRegressionModelParameters`](xref:Microsoft.ML.Trainers.LinearRegressionModelParameters), while [LbfgsMaximumEntropyMulticlassTrainer](xref:Microsoft.ML.Trainers.LbfgsMaximumEntropyMulticlassTrainer) outputs [`MaximumEntropyModelParameters`](xref:Microsoft.ML.Trainers.MaximumEntropyModelParameters). When extracting model parameters, cast to the appropriate type. -## Re-train model +## Retrain a model -The process for retraining a model is no different than that of training a model. The only difference is, the [`Fit`](xref:Microsoft.ML.Trainers.OnlineLinearTrainer%602.Fit%2A) method in addition to the data also takes as input the original learned model parameters and uses them as a starting point in the re-training process. +The process for retraining a model is no different than that of training a model. The only difference is, the [`Fit`](xref:Microsoft.ML.Trainers.OnlineLinearTrainer%602.Fit%2A) method in addition to the data also takes the original learned model parameters as input and uses them as a starting point in the retraining process. ```csharp // New Data @@ -99,11 +99,11 @@ RegressionPredictionTransformer retrainedModel .Fit(transformedNewData, originalModelParameters); ``` -At this point, you can save your re-trained model and use it in your application. For more information, see the [save and load a trained model](save-load-machine-learning-models-ml-net.md) and [make predictions with a trained model](machine-learning-model-predictions-ml-net.md) guides. +At this point, you can save your retrained model and use it in your application. For more information, see the [save and load a trained model](save-load-machine-learning-models-ml-net.md) and [make predictions with a trained model](machine-learning-model-predictions-ml-net.md) guides. ## Compare model parameters -How do you know if re-training actually happened? One way would be to compare whether the re-trained model's parameters are different than those of the original model. The code sample below compares the original against the re-trained model weights and outputs them to the console. +How do you know if retraining actually happened? One way would be to compare whether the retrained model's parameters are different than those of the original model. The following code sample compares the original against the retrained model weights and outputs them to the console. ```csharp // Extract Model Parameters of re-trained model @@ -121,11 +121,11 @@ for(int i=0;i < weightDiffs.Count();i++) } ``` -The table below shows what the output might look like. +The following table shows what the output might look like. -|Original | Retrained | Difference | -|---|---|---| -| 33039.86 | 56293.76 | -23253.9 | -| 29099.14 | 49586.03 | -20486.89 | -| 28938.38 | 48609.23 | -19670.85 | -| 30484.02 | 53745.43 | -23261.41 | +| Original | Retrained | Difference | +|----------|-----------|------------| +| 33039.86 | 56293.76 | -23253.9 | +| 29099.14 | 49586.03 | -20486.89 | +| 28938.38 | 48609.23 | -19670.85 | +| 30484.02 | 53745.43 | -23261.41 | diff --git a/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md b/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md index 5fe470f8d64da..b6147ce8b494e 100644 --- a/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md +++ b/docs/machine-learning/how-to-guides/serve-model-serverless-azure-functions-ml-net.md @@ -26,7 +26,7 @@ This sample is a **C# HTTP Trigger Azure Functions application** that uses a pre ## Create Azure Functions project -1. In Visual Studio 2022 open the **Create a new project** dialog. +1. In Visual Studio 2022 open the **Create a new project** dialog. 1. In the "Create a new project" dialog, select the **Azure Functions** project template. 1. In the **Name** text box, type "SentimentAnalysisFunctionsApp" and select the **Next** button. 1. In the "Additional information dialog", leave all the defaults as is and select the **Create** button. @@ -53,7 +53,7 @@ This sample is a **C# HTTP Trigger Azure Functions application** that uses a pre Create a class to predict sentiment. Add a new class to your project: -1. In **Solution Explorer**, right-click the project, and then select **Add** > **New Azure Function...**. +1. In **Solution Explorer**, right-click the project, and then select **Add** > **New Azure Function**. 1. In the **Add New Item** dialog box, select **Azure Function** and change the **Name** field to *AnalyzeSentiment.cs*. Then, select the **Add** button. diff --git a/docs/machine-learning/index.yml b/docs/machine-learning/index.yml index b56448fb17dd9..70b475ca45e60 100644 --- a/docs/machine-learning/index.yml +++ b/docs/machine-learning/index.yml @@ -1,29 +1,27 @@ ### YamlMime:Landing -title: ML.NET Documentation +title: ML.NET documentation summary: Learn how to use open-source ML.NET to build custom machine learning models and integrate them into apps. Tutorials, code examples, and more show you how. metadata: - title: ML.NET Documentation - Tutorials, API Reference + title: ML.NET documentation - Tutorials, API reference description: Learn how to use open-source ML.NET to build custom machine learning models and integrate them into apps. Tutorials, code examples, and more show you how. ms.service: dotnet-ml ms.topic: landing-page ms.collection: collection author: natke ms.author: nakersha - ms.date: 10/30/2019 - + ms.date: 04/15/2024 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new landingContent: - # Basics - - title: ML.NET Basics + - title: ML.NET basics linkLists: - linkListType: overview links: - - text: What is ML.NET? + - text: What is the ML.NET API? url: how-does-mldotnet-work.md - text: What is Model Builder? url: automate-training-with-model-builder.md @@ -54,7 +52,7 @@ landingContent: - text: Install the CLI on macOS, Windows, or Linux (low-code) url: how-to-guides/install-ml-net-cli.md - # Tutorials - scenarios + # Tutorials - scenarios - title: Tutorials linkLists: - linkListType: learn @@ -84,7 +82,6 @@ landingContent: - text: Build a movie recommender (API) url: tutorials/movie-recommendation.md - # API Card - title: How-to guides linkLists: @@ -109,6 +106,8 @@ landingContent: - linkListType: reference links: - text: ML.NET API reference - url: ../../api/index.md?view=ml-dotnet + url: ../../api/index.md?view=ml-dotnet&preserve-view=true + - text: ML.NET CLI reference + url: reference/ml-net-cli-reference.md - text: ML.NET samples url: https://github.com/dotnet/machinelearning-samples diff --git a/docs/machine-learning/overview.md b/docs/machine-learning/overview.md new file mode 100644 index 0000000000000..3278c659079da --- /dev/null +++ b/docs/machine-learning/overview.md @@ -0,0 +1,21 @@ +--- +title: Overview of ML.NET +description: Learn about the components that make up ML.NET. +ms.date: 04/15/2024 +--- + +# Overview of ML.NET + +ML.NET is an open-source, cross-platform machine learning framework for .NET developers that enables integration of custom machine learning models into .NET applications. It encompasses an [API](how-does-mldotnet-work.md), which consists of different NuGet packages, a Visual Studio extension called [Model Builder](automate-training-with-model-builder.md), and a [command-line interface](automate-training-with-cli.md) that's installed as a .NET tool. + +ML.NET packages: + +- [Microsoft.ML](https://www.nuget.org/packages/Microsoft.ML) +- [Microsoft.ML.AutoML](https://www.nuget.org/packages/Microsoft.ML.AutoML) +- [Microsoft.ML.Probabilistic](https://www.nuget.org/packages/Microsoft.ML.Probabilistic) +- [Microsoft.ML.Tokenizers](https://www.nuget.org/packages/Microsoft.ML.Tokenizers) +- [Many other packages](https://www.nuget.org/profiles/MLNET) + +Visual Studio extension: + +- [Model Builder extension for Visual Studio](https://marketplace.visualstudio.com/items?itemName=MLNET.ModelBuilder2022) diff --git a/docs/machine-learning/reference/ml-net-cli-reference.md b/docs/machine-learning/reference/ml-net-cli-reference.md index 69f3594a04a74..4106a0f784f3c 100644 --- a/docs/machine-learning/reference/ml-net-cli-reference.md +++ b/docs/machine-learning/reference/ml-net-cli-reference.md @@ -10,7 +10,7 @@ ms.custom: mlnet-tooling The `classification`, `regression`, and `recommendation` commands are the main commands provided by the ML.NET CLI tool. These commands allow you to generate good quality ML.NET models for classification, regression, and recommendation models using automated machine learning (AutoML) as well as the example C# code to run/score that model. In addition, the C# code to train the model is generated for you to research the algorithm and settings of the model. > [!NOTE] -> This topic refers to ML.NET CLI and ML.NET AutoML, which are currently in Preview, and material may be subject to change. +> This article refers to ML.NET CLI and ML.NET AutoML, which are currently in Preview, and material may be subject to change. ## Overview @@ -125,7 +125,7 @@ mlnet regression ### Recommendation options -Running `mlnet recommendation` will train a recommendation model. Choose this command if you want an ML Model to recommend items to users based on ratings (e.g. product recommendation). +Running `mlnet recommendation` will train a recommendation model. Choose this command if you want an ML Model to recommend items to users based on ratings (e.g. product recommendation). ```console mlnet recommendation diff --git a/docs/machine-learning/resources/azure-training-concepts-model-builder.md b/docs/machine-learning/resources/azure-training-concepts-model-builder.md index a78eac6a8d1eb..6a13cadce32cc 100644 --- a/docs/machine-learning/resources/azure-training-concepts-model-builder.md +++ b/docs/machine-learning/resources/azure-training-concepts-model-builder.md @@ -57,8 +57,8 @@ Training on Azure is only available for the Model Builder image classification s Once training is complete, two projects are added to your solution with the following suffixes: -- *ConsoleApp*: A C# .NET Core console application that provides starter code to build the prediction pipeline and make predictions. -- *Model*: A C# .NET Standard application that contains the data models that define the schema of input and output model data as well as the following assets: +- *ConsoleApp*: A C# console app that provides starter code to build the prediction pipeline and make predictions. +- *Model*: A C# .NET Standard app that contains the data models that define the schema of input and output model data as well as the following assets: - bestModel.onnx: A serialized version of the model in Open Neural Network Exchange (ONNX) format. ONNX is an open source format for AI models that supports interoperability between frameworks like ML.NET, PyTorch and TensorFlow. - bestModelMap.json: A list of categories used when making predictions to map the model output to a text category. diff --git a/docs/machine-learning/resources/metrics.md b/docs/machine-learning/resources/metrics.md index 418c98777e1d7..5d15b51242dcc 100644 --- a/docs/machine-learning/resources/metrics.md +++ b/docs/machine-learning/resources/metrics.md @@ -18,7 +18,7 @@ For example, for the classification task, the model is evaluated by measuring ho | **Accuracy** | [Accuracy](https://en.wikipedia.org/wiki/Accuracy_and_precision#In_binary_classification) is the proportion of correct predictions with a test data set. It is the ratio of number of correct predictions to the total number of input samples. It works well if there are similar number of samples belonging to each class.| **The closer to 1.00, the better**. But exactly 1.00 indicates an issue (commonly: label/target leakage, over-fitting, or testing with training data). When the test data is unbalanced (where most of the instances belong to one of the classes), the dataset is small, or scores approach 0.00 or 1.00, then accuracy doesn't really capture the effectiveness of a classifier and you need to check additional metrics. | | **AUC** | [aucROC](https://en.wikipedia.org/wiki/Receiver_operating_characteristic) or *Area under the curve* measures the area under the curve created by sweeping the true positive rate vs. the false positive rate. | **The closer to 1.00, the better**. It should be greater than 0.50 for a model to be acceptable. A model with AUC of 0.50 or less is worthless. | | **AUCPR** | aucPR or *Area under the curve of a Precision-Recall curve*: Useful measure of success of prediction when the classes are imbalanced (highly skewed datasets). | **The closer to 1.00, the better**. High scores close to 1.00 show that the classifier is returning accurate results (high precision), and returning a majority of all positive results (high recall). | -| **F1-score** | [F1 score](https://en.wikipedia.org/wiki/F1_score) also known as *balanced F-score or F-measure*. It's the harmonic mean of the precision and recall. F1 Score is helpful when you want to seek a balance between Precision and Recall.| **The closer to 1.00, the better**. An F1 score reaches its best value at 1.00 and worst score at 0.00. It tells you how precise your classifier is. | +| **F1-score** | [F1 score](https://en.wikipedia.org/wiki/F1_score) also known as *balanced F-score or F-measure*. It's the harmonic mean of the precision and recall. F1 Score is helpful when you want to seek a balance between Precision and Recall.| **The closer to 1.00, the better**. An F1 score reaches its best value at 1.00 and worst score at 0.00. It tells you how precise your classifier is. | For further details on binary classification metrics read the following articles: @@ -31,7 +31,7 @@ For further details on binary classification metrics read the following articles | Metrics | Description | Look for | |-----------|-----------------------|-----------| | **Micro-Accuracy** | [Micro-average Accuracy](xref:Microsoft.ML.Data.MulticlassClassificationMetrics.MicroAccuracy) aggregates the contributions of all classes to compute the average metric. It is the fraction of instances predicted correctly. The micro-average does not take class membership into account. Basically, every sample-class pair contributes equally to the accuracy metric. | **The closer to 1.00, the better**. In a multi-class classification task, micro-accuracy is preferable over macro-accuracy if you suspect there might be class imbalance (i.e you may have many more examples of one class than of other classes).| -| **Macro-Accuracy** | [Macro-average Accuracy](xref:Microsoft.ML.Data.MulticlassClassificationMetrics.MacroAccuracy) is the average accuracy at the class level. The accuracy for each class is computed and the macro-accuracy is the average of these accuracies. Basically, every class contributes equally to the accuracy metric. Minority classes are given equal weight as the larger classes. The macro-average metric gives the same weight to each class, no matter how many instances from that class the dataset contains. | **The closer to 1.00, the better**. It computes the metric independently for each class and then takes the average (hence treating all classes equally) | +| **Macro-Accuracy** | [Macro-average Accuracy](xref:Microsoft.ML.Data.MulticlassClassificationMetrics.MacroAccuracy) is the average accuracy at the class level. The accuracy for each class is computed and the macro-accuracy is the average of these accuracies. Basically, every class contributes equally to the accuracy metric. Minority classes are given equal weight as the larger classes. The macro-average metric gives the same weight to each class, no matter how many instances from that class the dataset contains. | **The closer to 1.00, the better**. It computes the metric independently for each class and then takes the average (hence treating all classes equally) | | **Log-loss**| Logarithmic loss measures the performance of a classification model where the prediction input is a probability value between 0.00 and 1.00. Log-loss increases as the predicted probability diverges from the actual label. | **The closer to 0.00, the better**. A perfect model would have a log-loss of 0.00. The goal of our machine learning models is to minimize this value.| | **Log-Loss Reduction** | [Logarithmic loss reduction](xref:Microsoft.ML.Data.MulticlassClassificationMetrics.LogLossReduction) can be interpreted as the advantage of the classifier over a random prediction.| **Ranges from -inf and 1.00, where 1.00 is perfect predictions and 0.00 indicates mean predictions**. For example, if the value equals 0.20, it can be interpreted as "the probability of a correct prediction is 20% better than random guessing"| diff --git a/docs/machine-learning/resources/tasks.md b/docs/machine-learning/resources/tasks.md index ff841f673482f..33c2756e628ba 100644 --- a/docs/machine-learning/resources/tasks.md +++ b/docs/machine-learning/resources/tasks.md @@ -183,7 +183,7 @@ This trainer outputs the following: ## Ranking -A ranking task constructs a ranker from a set of labeled examples. This example set consists of instance groups that can be scored with a given criteria. The ranking labels are { 0, 1, 2, 3, 4 } for each instance. The ranker is trained to rank new instance groups with unknown scores for each instance. ML.NET ranking learners are [machine learned ranking](https://en.wikipedia.org/wiki/Learning_to_rank) based. +A ranking task constructs a ranker from a set of labeled examples. This example set consists of instance groups that can be scored with a given criteria. The ranking labels are { 0, 1, 2, 3, 4 } for each instance. The ranker is trained to rank new instance groups with unknown scores for each instance. ML.NET ranking learners are [machine learned ranking](https://en.wikipedia.org/wiki/Learning_to_rank) based. ### Ranking training algorithms diff --git a/docs/machine-learning/toc.yml b/docs/machine-learning/toc.yml index 5a39075836060..dc2807636777d 100644 --- a/docs/machine-learning/toc.yml +++ b/docs/machine-learning/toc.yml @@ -2,21 +2,24 @@ items: - name: ML.NET href: index.yml - name: Overview + href: overview.md +- name: Model Builder & CLI items: - - name: Model Builder & CLI - items: - - name: The ML.NET Model Builder tool - href: automate-training-with-model-builder.md - - name: The ML.NET command-line interface - href: automate-training-with-cli.md - displayName: cli - - name: API - items: - - name: The ML.NET API - href: how-does-mldotnet-work.md - - name: What is Automated Machine Learning (AutoML)? - href: automated-machine-learning-mlnet.md - expanded: true + - name: The ML.NET Model Builder tool + href: automate-training-with-model-builder.md + - name: The ML.NET command-line interface + href: automate-training-with-cli.md + displayName: cli + expanded: true +- name: API + items: + - name: The ML.NET API + href: how-does-mldotnet-work.md + - name: What is Automated Machine Learning (AutoML)? + href: automated-machine-learning-mlnet.md + expanded: true +- name: What's new + href: whats-new/overview.md - name: Tutorials items: - name: Model Builder & CLI @@ -136,10 +139,6 @@ items: href: /azure/machine-learning/how-to-use-automl-onnx-model-dotnet?toc=/dotnet/machine-learning/how-to-guides/toc.json&bc=/dotnet/machine-learning/how-to-guides/toc.json - name: Reference items: - - name: ML.NET API reference - href: ../../api/index.md?view=ml-dotnet&preserve-view=true - - name: ML.NET Preview API reference - href: ../../api/index.md?view=ml-dotnet-preview&preserve-view=true - name: CLI reference href: reference/ml-net-cli-reference.md - name: Resources diff --git a/docs/machine-learning/tutorials/github-issue-classification.md b/docs/machine-learning/tutorials/github-issue-classification.md index 0a16631455c5a..4a44ee749a3e7 100644 --- a/docs/machine-learning/tutorials/github-issue-classification.md +++ b/docs/machine-learning/tutorials/github-issue-classification.md @@ -8,7 +8,7 @@ ms.custom: mvc, title-hack-0516 --- # Tutorial: Categorize support issues using multiclass classification with ML.NET -This sample tutorial illustrates using ML.NET to create a GitHub issue classifier to train a model that classifies and predicts the Area label for a GitHub issue via a .NET Core console application using C# in Visual Studio. +This sample tutorial illustrates using ML.NET to create a GitHub issue classifier to train a model that classifies and predicts the Area label for a GitHub issue via a .NET console application using C# in Visual Studio. In this tutorial, you learn how to: > [!div class="checklist"] @@ -226,7 +226,7 @@ Use the [Predict()](xref:Microsoft.ML.PredictionEngine%602.Predict%2A) function ### Use the model: prediction results -Display `GitHubIssue` and corresponding `Area` label prediction in order to share the results and act on them accordingly. Create a display for the results using the following code: +Display `GitHubIssue` and corresponding `Area` label prediction in order to share the results and act on them accordingly. Create a display for the results using the following code: [!code-csharp[OutputPrediction](./snippets/github-issue-classification/csharp/Program.cs#OutputPrediction)] @@ -270,7 +270,7 @@ Notice the use of the [Transform()](xref:Microsoft.ML.ITransformer.Transform%2A) The following metrics are evaluated for multiclass classification: -* Micro Accuracy - Every sample-class pair contributes equally to the accuracy metric. You want Micro Accuracy to be as close to one as possible. +* Micro Accuracy - Every sample-class pair contributes equally to the accuracy metric. You want Micro Accuracy to be as close to one as possible. * Macro Accuracy - Every class contributes equally to the accuracy metric. Minority classes are given equal weight as the larger classes. You want Macro Accuracy to be as close to one as possible. diff --git a/docs/machine-learning/tutorials/health-violation-classification-model-builder.md b/docs/machine-learning/tutorials/health-violation-classification-model-builder.md index bf1843ab80e8a..daa4268599b21 100644 --- a/docs/machine-learning/tutorials/health-violation-classification-model-builder.md +++ b/docs/machine-learning/tutorials/health-violation-classification-model-builder.md @@ -31,11 +31,11 @@ For a list of prerequisites and installation instructions, visit the [Model Buil ## Model Builder multiclass classification overview -This sample creates a C# .NET Core console application that categorizes the risk of health violations using a machine learning model built with Model Builder. You can find the source code for this tutorial at the [dotnet/machinelearning-samples](https://github.com/dotnet/machinelearning-samples/tree/main/samples/modelbuilder/MulticlassClassification_RestaurantViolations) GitHub repository. +This sample creates a C# console application that categorizes the risk of health violations using a machine learning model built with Model Builder. You can find the source code for this tutorial at the [dotnet/machinelearning-samples](https://github.com/dotnet/machinelearning-samples/tree/main/samples/modelbuilder/MulticlassClassification_RestaurantViolations) GitHub repository. ## Create a console application -1. Create a **C# .NET Core console application** called "RestaurantViolations". +Create a **C# console application** called "RestaurantViolations". ## Prepare and understand the data @@ -57,11 +57,11 @@ Each row in the dataset contains information regarding violations observed durin The `label` is the column you want to predict. When performing a classification task, the goal is to assign a category (text or numerical). In this classification scenario, the severity of the violation is assigned the value of low, moderate, or high risk. Therefore, the **RiskCategory** is the label. The `features` are the inputs you give the model to predict the `label`. In this case, the **InspectionType** and **ViolationDescription** are used as features or inputs to predict the **RiskCategory**. -## Create Model Builder Config File +## Create Model Builder config file When first adding Model Builder to the solution it will prompt you to create an `mbconfig` file. The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. -1. In **Solution Explorer**, right-click the *RestaurantViolations* project, and select **Add** > **Machine Learning Model...**. +1. In **Solution Explorer**, right-click the *RestaurantViolations* project, and select **Add** > **Machine Learning Model**. 1. Name the `mbconfig` project **RestaurantViolationsPrediction**, and click the **Add** button. ## Choose a scenario diff --git a/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md b/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md index 949e0a9a66644..7018aa558c54f 100644 --- a/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md +++ b/docs/machine-learning/tutorials/image-classification-api-transfer-learning.md @@ -28,7 +28,7 @@ In this tutorial, you learn how to: ## Image classification transfer learning sample overview -This sample is a C# .NET Core console application that classifies images using a pretrained deep learning TensorFlow model. The code for this sample can be found on the [samples browser](/samples/dotnet/machinelearning-samples/mlnet-image-classification-transfer-learning/). +This sample is a C# console application that classifies images using a pretrained deep learning TensorFlow model. The code for this sample can be found on the [samples browser](/samples/dotnet/machinelearning-samples/mlnet-image-classification-transfer-learning/). ## Understand the problem diff --git a/docs/machine-learning/tutorials/image-classification-model-builder.md b/docs/machine-learning/tutorials/image-classification-model-builder.md index ef2e9c9712607..a7e8b2f89ac66 100644 --- a/docs/machine-learning/tutorials/image-classification-model-builder.md +++ b/docs/machine-learning/tutorials/image-classification-model-builder.md @@ -61,7 +61,7 @@ The EuroSAT dataset contains a collection of satellite images divided into ten c When first adding Model Builder to the solution it will prompt you to create an `mbconfig` file. The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. -1. In Solution Explorer, right-click the **LandUse** project, and select **Add > Machine Learning Model...**. +1. In Solution Explorer, right-click the **LandUse** project, and select **Add > Machine Learning Model**. 1. In the dialog, name the Model Builder project **LandUse**, and click **Add**. ## Choose a scenario diff --git a/docs/machine-learning/tutorials/image-classification.md b/docs/machine-learning/tutorials/image-classification.md index 15b13ad435768..cbde83493f58e 100644 --- a/docs/machine-learning/tutorials/image-classification.md +++ b/docs/machine-learning/tutorials/image-classification.md @@ -69,7 +69,7 @@ This tutorial uses the TensorFlow [Inception](https://storage.googleapis.com/dow Because the `Inception model` has already been pre-trained on thousands of different images, internally it contains the [image features](https://en.wikipedia.org/wiki/Feature_(computer_vision)) needed for image identification. We can make use of these internal image features in the model to train a new model with far fewer classes. -As shown in the following diagram, you add a reference to the ML.NET NuGet packages in your .NET Core or .NET Framework applications. Under the covers, ML.NET includes and references the native `TensorFlow` library that allows you to write code that loads an existing trained `TensorFlow` model file. +As shown in the following diagram, you add a reference to the ML.NET NuGet packages in your .NET or .NET Framework applications. Under the covers, ML.NET includes and references the native `TensorFlow` library that allows you to write code that loads an existing trained `TensorFlow` model file. ![TensorFlow transform ML.NET Arch diagram](./media/image-classification/tensorflow-mlnet.png) @@ -85,7 +85,7 @@ See [Deep learning vs. machine learning](/azure/machine-learning/concept-deep-le ### Data -There are two data sources: the `.tsv` file, and the image files. The `tags.tsv` file contains two columns: the first one is defined as `ImagePath` and the second one is the `Label` corresponding to the image. The following example file doesn't have a header row, and looks like this: +There are two data sources: the `.tsv` file, and the image files. The `tags.tsv` file contains two columns: the first one is defined as `ImagePath` and the second one is the `Label` corresponding to the image. The following example file doesn't have a header row, and looks like this: ```tsv @@ -171,7 +171,7 @@ The training and testing images are located in the assets folders that you'll do ### Initialize variables -1. Initialize the `mlContext` variable with a new instance of `MLContext`. Replace the `Console.WriteLine("Hello World!")` line with the following code: +1. Initialize the `mlContext` variable with a new instance of `MLContext`. Replace the `Console.WriteLine("Hello World!")` line with the following code: [!code-csharp[CreateMLContext](./snippets/image-classification/csharp/Program.cs#CreateMLContext)] @@ -321,7 +321,7 @@ An ML.NET model pipeline is a chain of estimators. No execution happens during p [!code-csharp[SaveModel](./snippets/image-classification/csharp/Program.cs#ReturnModel)] -## Run the application! +## Run the application 1. Add the call to `GenerateModel` after the creation of the class: diff --git a/docs/machine-learning/tutorials/movie-recommendation-model-builder.md b/docs/machine-learning/tutorials/movie-recommendation-model-builder.md index f7d52ab4461eb..d484998908d4b 100644 --- a/docs/machine-learning/tutorials/movie-recommendation-model-builder.md +++ b/docs/machine-learning/tutorials/movie-recommendation-model-builder.md @@ -54,7 +54,7 @@ Each row in the dataset contains information regarding a movie rating. When first adding Model Builder to the solution it will prompt you to create an `mbconfig` file. The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. -1. In Solution Explorer, right-click the **MovieRecommender** project, and select **Add > Machine Learning Model...**. +1. In Solution Explorer, right-click the **MovieRecommender** project, and select **Add > Machine Learning Model**. 1. In the dialog, name the Model Builder project **MovieRecommender**, and click **Add**. ## Choose a scenario diff --git a/docs/machine-learning/tutorials/movie-recommendation.md b/docs/machine-learning/tutorials/movie-recommendation.md index 0b0dd10c85442..4130d7eb1a731 100644 --- a/docs/machine-learning/tutorials/movie-recommendation.md +++ b/docs/machine-learning/tutorials/movie-recommendation.md @@ -1,6 +1,6 @@ --- title: 'Tutorial: Build a movie recommender - matrix factorization' -description: This tutorial shows you how to build a movie recommender with ML.NET in a .NET Core console application. The steps use C# and Visual Studio 2019. +description: This tutorial shows you how to build a movie recommender with ML.NET in a .NET console application. The steps use C# and Visual Studio 2019. author: briacht ms.date: 11/11/2021 ms.custom: mvc, title-hack-0516 @@ -10,7 +10,7 @@ ms.topic: tutorial # Tutorial: Build a movie recommender using matrix factorization with ML.NET -This tutorial shows you how to build a movie recommender with ML.NET in a .NET Core console application. The steps use C# and Visual Studio 2019. +This tutorial shows you how to build a movie recommender with ML.NET in a .NET console application. The steps use C# and Visual Studio 2019. In this tutorial, you learn how to: > [!div class="checklist"] @@ -195,7 +195,7 @@ Choose the machine learning algorithm and append it to the data transformation d [!code-csharp[AddAlgorithm](./snippets/movie-recommendation/csharp/Program.cs#AddAlgorithm "Add the training algorithm with options")] -The [MatrixFactorizationTrainer](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization%28Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options%29) is your recommendation training algorithm. [Matrix Factorization](https://en.wikipedia.org/wiki/Matrix_factorization_(recommender_systems)) is a common approach to recommendation when you have data on how users have rated products in the past, which is the case for the datasets in this tutorial. There are other recommendation algorithms for when you have different data available (see the [Other recommendation algorithms](#other-recommendation-algorithms) section below to learn more). +The [MatrixFactorizationTrainer](xref:Microsoft.ML.RecommendationCatalog.RecommendationTrainers.MatrixFactorization%28Microsoft.ML.Trainers.MatrixFactorizationTrainer.Options%29) is your recommendation training algorithm. [Matrix Factorization](https://en.wikipedia.org/wiki/Matrix_factorization_(recommender_systems)) is a common approach to recommendation when you have data on how users have rated products in the past, which is the case for the datasets in this tutorial. There are other recommendation algorithms for when you have different data available (see the [Other recommendation algorithms](#other-recommendation-algorithms) section below to learn more). In this case, the `Matrix Factorization` algorithm uses a method called "collaborative filtering", which assumes that if User 1 has the same opinion as User 2 on a certain issue, then User 1 is more likely to feel the same way as User 2 about a different issue. diff --git a/docs/machine-learning/tutorials/object-detection-model-builder.md b/docs/machine-learning/tutorials/object-detection-model-builder.md index 3ff142410b6f9..6cd3843fed2c4 100644 --- a/docs/machine-learning/tutorials/object-detection-model-builder.md +++ b/docs/machine-learning/tutorials/object-detection-model-builder.md @@ -11,9 +11,7 @@ ms.custom: mlnet-tooling # Tutorial: Detect stop signs in images with Model Builder -Learn how to build an object detection model using ML.NET Model Builder and Azure Machine Learning to detect and locate stop signs in images. - -In this tutorial, you learn how to: +In this tutorial, you learn how to build an object detection model using ML.NET Model Builder and Azure Machine Learning to detect and locate stop signs in images. > [!div class="checklist"] > @@ -47,7 +45,7 @@ Some use cases for object detection include: - Object Counting - Activity Recognition -This sample creates a C# .NET Core console application that detects stop signs in images using a machine learning model built with Model Builder. You can find the source code for this tutorial at the [dotnet/machinelearning-samples](https://github.com/dotnet/machinelearning-samples/tree/main/samples/modelbuilder/ObjectDetection_StopSigns) GitHub repository. +This sample creates a C# console application that detects stop signs in images using a machine learning model built with Model Builder. You can find the source code for this tutorial at the [dotnet/machinelearning-samples](https://github.com/dotnet/machinelearning-samples/tree/main/samples/modelbuilder/ObjectDetection_StopSigns) GitHub repository. ## Prepare and understand the data @@ -62,14 +60,14 @@ The Stop Sign dataset consists of 50 images downloaded from [Unsplash](https://u ![VoTT Home Screen](../how-to-guides/media/vott/vott.png) 1. In **Project Settings**, change the **Display Name** to "StopSignObjDetection". -1. Change the **Security Token** to *Generate New Security Token*. +1. Change the **Security Token** to _Generate New Security Token_. 1. Next to **Source Connection**, select **Add Connection**. -1. In **Connection Settings**, change the **Display Name** for the source connection to "StopSignImages", and select *Local File System* as the **Provider**. For the **Folder Path**, select the *Stop-Signs* folder which contains the 50 training images, and then select **Save Connection**. +1. In **Connection Settings**, change the **Display Name** for the source connection to "StopSignImages", and select _Local File System_ as the **Provider**. For the **Folder Path**, select the _Stop-Signs_ folder which contains the 50 training images, and then select **Save Connection**. ![VoTT New Connection Dialog](./media/object-detection-model-builder/vott-new-connection.png) -1. In **Project Settings**, change the **Source Connection** to *StopSignImages* (the connection you just created). -1. Change the **Target Connection** to *StopSignImages* as well. Your **Project Settings** should now look similar to this screenshot: +1. In **Project Settings**, change the **Source Connection** to _StopSignImages_ (the connection you just created). +1. Change the **Target Connection** to _StopSignImages_ as well. Your **Project Settings** should now look similar to this screenshot: ![VoTT Project Settings Dialog](./media/object-detection-model-builder/vott-new-project.png) @@ -99,8 +97,8 @@ You should now see a window with preview images of all the training images on th Once you have labeled all of your training images, you can export the file that will be used by Model Builder for training. 1. Select the fourth icon in the left toolbar (the one with the diagonal arrow in a box) to go to the **Export Settings**. -1. Leave the **Provider** as *VoTT JSON*. -1. Change the **Asset State** to *Only tagged Assets*. +1. Leave the **Provider** as _VoTT JSON_. +1. Change the **Asset State** to _Only tagged Assets_. 1. Uncheck **Include Images**. If you include the images, then the training images will be copied to the export folder that is generated, which is not necessary. 1. Select **Save Export Settings**. @@ -110,15 +108,15 @@ Once you have labeled all of your training images, you can export the file that ![VoTT Export Button](../how-to-guides/media/vott/vott-export-button.png) -This export will create a new folder called *vott-json-export* in your *Stop-Sign-Images* folder and will generate a JSON file named *StopSignObjDetection-export* in that new folder. You will use this JSON file in the next steps for training an object detection model in Model Builder. +This export will create a new folder called _vott-json-export_ in your _Stop-Sign-Images_ folder and will generate a JSON file named _StopSignObjDetection-export_ in that new folder. You will use this JSON file in the next steps for training an object detection model in Model Builder. ## Create a console application -In Visual Studio, create a **C# .NET Core console application** called *StopSignDetection*. +In Visual Studio, create a **C# console application** called _StopSignDetection_. ## Create an `mbconfig` file -1. In **Solution Explorer**, right-click the *StopSignDetection* project, and select **Add** > **Machine Learning Model...** to open the Model Builder UI. +1. In **Solution Explorer**, right-click the _StopSignDetection_ project, and select **Add** > **Machine Learning Model** to open the Model Builder UI. 1. In the dialog, name the Model Builder project **StopSignDetection**, and click **Add**. ## Choose a scenario @@ -127,7 +125,7 @@ For this sample, the scenario is object detection. In the **Scenario** step of M ![Model Builder wizard in Visual Studio](./media/object-detection-model-builder/obj-det-scenario.png) -> If you don't see *Object Detection* in the list of scenarios, you may need to [update your version of Model Builder](https://marketplace.visualstudio.com/items?itemName=MLNET.07). +> If you don't see _Object Detection_ in the list of scenarios, you may need to [update your version of Model Builder](https://marketplace.visualstudio.com/items?itemName=MLNET.07). ## Choose the training environment @@ -179,7 +177,7 @@ In the **Data** step of Model Builder, you will select your training dataset. > [!IMPORTANT] > Model Builder currently only accepts the format of JSON [generated by VoTT](../how-to-guides/label-images-for-object-detection-using-vott.md). -1. Select the button inside **Input** section and use the File Explorer to find the `StopSignObjDetection-export.json` which should be located in the *Stop-Signs/vott-json-export* directory. +1. Select the button inside **Input** section and use the File Explorer to find the `StopSignObjDetection-export.json` which should be located in the _Stop-Signs/vott-json-export_ directory. ![Model Builder Data Step](./media/object-detection-model-builder/obj-det-data.png) @@ -205,7 +203,7 @@ In the Evaluate screen, you get an overview of the results from the training pro ![Model Builder Evaluate Step](./media/object-detection-model-builder/obj-det-evaluate.png) -In this case, the accuracy says 100%, which means that the model is more than likely *overfit* due to too few images in the dataset. +In this case, the accuracy says 100%, which means that the model is more than likely _overfit_ due to too few images in the dataset. You can use the **Try your model** experience to quickly check whether your model is performing as expected. diff --git a/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md b/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md index c0b556bd67aff..56db29b26342e 100644 --- a/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md +++ b/docs/machine-learning/tutorials/phone-calls-anomaly-detection.md @@ -1,6 +1,6 @@ --- title: 'Tutorial: Detect anomalies in phone calls' -description: Learn how to build an anomaly detection application for time series data. This tutorial creates a .NET Core console application using C# in Visual Studio 2019. +description: Learn how to build an anomaly detection application for time series data. This tutorial creates a .NET console application using C# in Visual Studio 2019. ms.date: 07/28/2021 ms.topic: tutorial ms.custom: mvc @@ -8,7 +8,7 @@ ms.custom: mvc --- # Tutorial: Detect anomalies in time series with ML.NET -Learn how to build an anomaly detection application for time series data. This tutorial creates a .NET Core console application using C# in Visual Studio 2019. +Learn how to build an anomaly detection application for time series data. This tutorial creates a .NET console application using C# in Visual Studio 2019. In this tutorial, you learn how to: > [!div class="checklist"] diff --git a/docs/machine-learning/tutorials/predict-prices-with-model-builder.md b/docs/machine-learning/tutorials/predict-prices-with-model-builder.md index 49b3172486b59..8d5c551a646d0 100644 --- a/docs/machine-learning/tutorials/predict-prices-with-model-builder.md +++ b/docs/machine-learning/tutorials/predict-prices-with-model-builder.md @@ -11,11 +11,8 @@ ms.custom: mvc, mlnet-tooling # Tutorial: Predict prices using regression with Model Builder -Learn how to use ML.NET Model Builder to build a regression model to predict prices. The .NET console app that you develop in this tutorial predicts taxi fares based on historical New York taxi fare data. +In this tutorial, you learn how to use ML.NET Model Builder to build a regression model to predict prices. The .NET console app that you develop in this tutorial predicts taxi fares based on historical New York taxi fare data. -The Model Builder price prediction template can be used for any scenario requiring a numerical prediction value. Example scenarios include: house price prediction, demand prediction, and sales forecasting. - -In this tutorial, you learn how to: > [!div class="checklist"] > > - Prepare and understand the data @@ -26,13 +23,15 @@ In this tutorial, you learn how to: > - Evaluate the model > - Use the model for predictions -## Pre-requisites +The Model Builder price prediction template can be used for any scenario requiring a numerical prediction value. Example scenarios include: house price prediction, demand prediction, and sales forecasting. + +## Prerequisites For a list of pre-requisites and installation instructions, visit the [Model Builder installation guide](../how-to-guides/install-model-builder.md). ## Create a console application -1. Create a **C# .NET Core Console Application** called "TaxiFarePrediction". Make sure **Place solution and project in the same directory** is **unchecked** (VS 2019). +Create a **C# Console Application** called "TaxiFarePrediction". Make sure **Place solution and project in the same directory** is **unchecked**. ## Prepare and understand the data @@ -64,11 +63,11 @@ Each row in the `taxi-fare-train.csv` data set contains details of trips made by The `label` is the column you want to predict. When performing a regression task, the goal is to predict a numerical value. In this price prediction scenario, the cost of a taxi ride is being predicted. Therefore, the **fare_amount** is the label. The identified `features` are the inputs you give the model to predict the `label`. In this case, the rest of the columns with the exception of **trip_time_in_secs** are used as features or inputs to predict the fare amount. -## Create Model Builder Config File +## Create Model Builder config file When first adding Model Builder to the solution it will prompt you to create an `mbconfig` file. The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. -1. In **Solution Explorer**, right-click the *TaxiFarePrediction* project, and select **Add** > **Machine Learning Model...**. +1. In **Solution Explorer**, right-click the *TaxiFarePrediction* project, and select **Add** > **Machine Learning Model**. 1. Name the `mbconfig` project **TaxiFarePrediction**, and click the **Add** button. ## Choose a scenario @@ -136,7 +135,7 @@ This step will have project templates that you can use to consume the model. Thi - Console App - Web API -### Console App +### Console app When adding a console app to your solution, you will be prompted to name the project. @@ -179,19 +178,7 @@ When adding a web API to your solution, you will be prompted to name the project 15.020833 ``` -## Next Steps - -In this tutorial, you learned how to: -> [!div class="checklist"] -> -> - Prepare and understand the data -> - Choose a scenario -> - Load the data -> - Train the model -> - Evaluate the model -> - Use the model for predictions - -### Additional Resources +## Related content To learn more about topics mentioned in this tutorial, visit the following resources: diff --git a/docs/machine-learning/tutorials/sales-anomaly-detection.md b/docs/machine-learning/tutorials/sales-anomaly-detection.md index f0bb97c0b9f00..e5cf7055f6426 100644 --- a/docs/machine-learning/tutorials/sales-anomaly-detection.md +++ b/docs/machine-learning/tutorials/sales-anomaly-detection.md @@ -1,6 +1,6 @@ --- title: 'Tutorial: Detect anomalies in product sales' -description: Learn how to build an anomaly detection application for product sales data. This tutorial creates a .NET Core console application using C# in Visual Studio 2019. +description: Learn how to build an anomaly detection application for product sales data. This tutorial creates a .NET console application using C# in Visual Studio 2019. ms.date: 11/11/2021 ms.topic: tutorial ms.custom: mvc, title-hack-0612 @@ -8,7 +8,7 @@ ms.custom: mvc, title-hack-0612 --- # Tutorial: Detect anomalies in product sales with ML.NET -Learn how to build an anomaly detection application for product sales data. This tutorial creates a .NET Core console application using C# in Visual Studio. +Learn how to build an anomaly detection application for product sales data. This tutorial creates a .NET console application using C# in Visual Studio. In this tutorial, you learn how to: > [!div class="checklist"] @@ -266,7 +266,7 @@ Alert Score P-Value ## Change point detection -`Change points` are persistent changes in a time series event stream distribution of values, like level changes and trends. These persistent changes last much longer than `spikes` and could indicate catastrophic event(s). `Change points` are not usually visible to the naked eye, but can be detected in your data using approaches such as in the following method. The following image is an example of a change point detection: +`Change points` are persistent changes in a time series event stream distribution of values, like level changes and trends. These persistent changes last much longer than `spikes` and could indicate catastrophic event(s). `Change points` are not usually visible to the naked eye, but can be detected in your data using approaches such as in the following method. The following image is an example of a change point detection: ![Screenshot that shows a change point detection.](./media/sales-anomaly-detection/change-point-detection.png) diff --git a/docs/machine-learning/tutorials/sentiment-analysis-cli.md b/docs/machine-learning/tutorials/sentiment-analysis-cli.md index fd7fa30884ae2..b984bb1eae21d 100644 --- a/docs/machine-learning/tutorials/sentiment-analysis-cli.md +++ b/docs/machine-learning/tutorials/sentiment-analysis-cli.md @@ -23,7 +23,7 @@ In this tutorial, you will do the following steps: > - Explore the generated C# code that was used to train the model > [!NOTE] -> This topic refers to the ML.NET CLI tool, which is currently in Preview, and material may be subject to change. For more information, visit the [ML.NET](https://dotnet.microsoft.com/apps/machinelearning-ai/ml-dotnet) page. +> This article refers to the ML.NET CLI tool, which is currently in Preview, and material may be subject to change. For more information, visit the [ML.NET](https://dotnet.microsoft.com/apps/machinelearning-ai/ml-dotnet) page. The ML.NET CLI is part of ML.NET and its main goal is to "democratize" ML.NET for .NET developers when learning ML.NET so you don't need to code from scratch to get started. @@ -31,7 +31,7 @@ You can run the ML.NET CLI on any command-prompt (Windows, Mac, or Linux) to gen ## Pre-requisites -- [.NET Core 6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0) or later +- [.NET 6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0) or later - (Optional) [Visual Studio](https://visualstudio.microsoft.com/vs/) - [ML.NET CLI](../how-to-guides/install-ml-net-cli.md) @@ -196,7 +196,7 @@ The creation of the model object (`ITransformer` loaded from a model's .zip file For the second object, the `PredictionEngine` object, it is not so easy because the `PredictionEngine` object is not thread-safe, therefore you cannot instantiate this object as singleton or static object in an ASP.NET Core app. This thread-safe and scalability problem is deeply discussed in this [Blog Post](https://devblogs.microsoft.com/cesardelatorre/how-to-optimize-and-run-ml-net-models-on-scalable-asp-net-core-webapis-or-web-apps/). -However, things got a lot easier for you than what's explained in that blog post. We worked on a simpler approach for you and have created a nice **'.NET Core Integration Package'** that you can easily use in your ASP.NET Core apps and services by registering it in the application DI services (Dependency Injection services) and then directly use it from your code. Check the following tutorial and example for doing that: +However, things got a lot easier for you than what's explained in that blog post. We worked on a simpler approach for you and have created a **'.NET Integration Package'** that you can easily use in your ASP.NET Core apps and services by registering it in the application DI services (Dependency Injection services) and then directly use it from your code. Check the following tutorial and example for doing that: - [Tutorial: Running ML.NET models on scalable ASP.NET Core web apps and WebAPIs](../how-to-guides/serve-model-web-api-ml-net.md) - [Sample: Scalable ML.NET model on ASP.NET Core WebAPI](https://aka.ms/mlnet-sample-netcoreintegrationpkg) diff --git a/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md b/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md index da5f718606b21..62d944f02c552 100644 --- a/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md +++ b/docs/machine-learning/tutorials/sentiment-analysis-model-builder.md @@ -58,7 +58,7 @@ Each row in the *wikipedia-detox-250-line-data.tsv* dataset represents a differe When first adding a machine learning model to the solution it will prompt you to create an `mbconfig` file. The `mbconfig` file keeps track of everything you do in Model Builder to allow you to reopen the session. -1. In **Solution Explorer**, right-click the *SentimentRazor* project, and select **Add** > **Machine Learning Model...**. +1. In **Solution Explorer**, right-click the *SentimentRazor* project, and select **Add** > **Machine Learning Model**. 1. In the dialog, name the Model Builder project **SentimentAnalysis.mbconfig**, and select **Add**. ## Choose a scenario @@ -106,7 +106,7 @@ The machine learning task used to train the sentiment analysis model in this tut The result of the training step will be one model that has the best performance. In the evaluate step of the Model Builder tool, the output section will contain the trainer used by the best-performing model in the as well as evaluation metrics. -If you're not satisfied with your evaluation metrics, some easy ways to try to improve model performance are to use more data. +If you're not satisfied with your evaluation metrics, some easy ways to try to improve model performance are to use more data. Otherwise, select the **Next step** button to move to the *Consume* step in Model Builder. @@ -229,16 +229,16 @@ The results returned by the `OnGetAnalyzeSentiment` will be dynamically displaye @{ ViewData["Title"] = "Home page"; } - +

Live Sentiment

- +

- +

Your sentiment is...

😡 😐 😍

- +
▲
@@ -246,7 +246,7 @@ The results returned by the `OnGetAnalyzeSentiment` will be dynamically displaye
-
+ ``` 1. Next, add css styling code to the end of the *site.css* page in the *wwwroot\css* directory: @@ -262,37 +262,37 @@ The results returned by the `OnGetAnalyzeSentiment` will be dynamically displaye padding-bottom: 0; border-radius: 1rem; } - + .sentiment h4 { font-size: 16px; text-align: center; margin: 0; padding: 0; } - + .sentiment p { font-size: 50px; } - + .sentiment .marker { position: relative; left: 22px; width: calc(100% - 68px); } - + .sentiment .marker > div { transition: 0.3s ease-in-out; position: absolute; margin-left: -30px; text-align: center; } - + .sentiment .marker > div > div { font-size: 50px; line-height: 20px; color: green; } - + .sentiment .marker > div label { font-size: 30px; color: gray; @@ -339,15 +339,15 @@ The results returned by the `OnGetAnalyzeSentiment` will be dynamically displaye break; default: updateMarker(45.0, "Neutral"); - } + } }); - } + } ``` 1. Finally, register the event handler and bind it to the `textarea` element with the `id=Message` attribute. ```javascript - $("#Message").on('change input paste', updateSentiment) + $("#Message").on('change input paste', updateSentiment) ``` ## Run the application diff --git a/docs/machine-learning/tutorials/sentiment-analysis.md b/docs/machine-learning/tutorials/sentiment-analysis.md index 63186bbd5033a..47542e73404c4 100644 --- a/docs/machine-learning/tutorials/sentiment-analysis.md +++ b/docs/machine-learning/tutorials/sentiment-analysis.md @@ -1,6 +1,6 @@ --- title: 'Tutorial: Analyze website comments - binary classification' -description: This tutorial shows you how to create a .NET Core console application that classifies sentiment from website comments and takes the appropriate action. The binary sentiment classifier uses C# in Visual Studio. +description: This tutorial shows you how to create a .NET console application that classifies sentiment from website comments and takes the appropriate action. The binary sentiment classifier uses C# in Visual Studio. ms.date: 11/04/2021 ms.topic: tutorial ms.custom: mvc @@ -8,7 +8,7 @@ ms.custom: mvc --- # Tutorial: Analyze sentiment of website comments with binary classification in ML.NET -This tutorial shows you how to create a .NET Core console application that classifies sentiment from website comments and takes the appropriate action. The binary sentiment classifier uses C# in Visual Studio 2022. +This tutorial shows you how to create a .NET console application that classifies sentiment from website comments and takes the appropriate action. The binary sentiment classifier uses C# in Visual Studio 2022. In this tutorial, you learn how to: > [!div class="checklist"] @@ -80,7 +80,7 @@ You can find the source code for this tutorial at the [dotnet/samples](https://g ### How the data was prepared -The input dataset class, `SentimentData`, has a `string` for user comments (`SentimentText`) and a `bool` (`Sentiment`) value of either 1 (positive) or 0 (negative) for sentiment. Both fields have [LoadColumn](xref:Microsoft.ML.Data.LoadColumnAttribute.%23ctor%28System.Int32%29) attributes attached to them, which describes the data file order of each field. In addition, the `Sentiment` property has a [ColumnName](xref:Microsoft.ML.Data.ColumnNameAttribute.%23ctor%2A) attribute to designate it as the `Label` field. The following example file doesn't have a header row, and looks like this: +The input dataset class, `SentimentData`, has a `string` for user comments (`SentimentText`) and a `bool` (`Sentiment`) value of either 1 (positive) or 0 (negative) for sentiment. Both fields have [LoadColumn](xref:Microsoft.ML.Data.LoadColumnAttribute.%23ctor%28System.Int32%29) attributes attached to them, which describes the data file order of each field. In addition, the `Sentiment` property has a [ColumnName](xref:Microsoft.ML.Data.ColumnNameAttribute.%23ctor%2A) attribute to designate it as the `Label` field. The following example file doesn't have a header row, and looks like this: |SentimentText |Sentiment (Label) | |--------------------------------------|----------| @@ -253,7 +253,7 @@ Use the following code to display the metrics: - The `AreaUnderRocCurve` metric indicates how confident the model is correctly classifying the positive and negative classes. You want the `AreaUnderRocCurve` to be as close to one as possible. -- The `F1Score` metric gets the model's F1 score, which is a measure of balance between [precision](../resources/glossary.md#precision) and [recall](../resources/glossary.md#recall). You want the `F1Score` to be as close to one as possible. +- The `F1Score` metric gets the model's F1 score, which is a measure of balance between [precision](../resources/glossary.md#precision) and [recall](../resources/glossary.md#recall). You want the `F1Score` to be as close to one as possible. ### Predict the test data outcome diff --git a/docs/machine-learning/tutorials/text-classification-tf.md b/docs/machine-learning/tutorials/text-classification-tf.md index 1b691a7cb2e8c..fb4149be59c22 100644 --- a/docs/machine-learning/tutorials/text-classification-tf.md +++ b/docs/machine-learning/tutorials/text-classification-tf.md @@ -23,7 +23,7 @@ You can find the source code for this tutorial at the [dotnet/samples](https://g ## Prerequisites -- [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) with the ".NET Desktop Development" workload installed. +* [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) with the ".NET Desktop Development" workload installed. ## Setup @@ -100,15 +100,15 @@ The variable length feature array is then resized to a fixed length of 600. This [!code-csharp[VariableLengthFeatures](./snippets/text-classification-tf/csharp/Program.cs#VariableLengthFeatures "Declare variable length features type")] - The `VariableLengthFeatures` property has a [VectorType](xref:Microsoft.ML.Data.VectorTypeAttribute.%23ctor%2A) attribute to designate it as a vector. All of the vector elements must be the same type. In data sets with a large number of columns, loading multiple columns as a single vector reduces the number of data passes when you apply data transformations. + The `VariableLengthFeatures` property has a [VectorType](xref:Microsoft.ML.Data.VectorTypeAttribute.%23ctor%2A) attribute to designate it as a vector. All of the vector elements must be the same type. In data sets with a large number of columns, loading multiple columns as a single vector reduces the number of data passes when you apply data transformations. - This class is used in the `ResizeFeatures` action. The names of its properties (in this case only one) are used to indicate which columns in the DataView can be used as the _input_ to the custom mapping action. + This class is used in the `ResizeFeatures` action. The names of its properties (in this case only one) are used to indicate which columns in the DataView can be used as the *input* to the custom mapping action. 1. Create a class for the fixed length features, after the `VariableLength` class: [!code-csharp[FixedLengthFeatures](./snippets/text-classification-tf/csharp/Program.cs#FixedLengthFeatures)] - This class is used in the `ResizeFeatures` action. The names of its properties (in this case only one) are used to indicate which columns in the DataView can be used as the _output_ of the custom mapping action. + This class is used in the `ResizeFeatures` action. The names of its properties (in this case only one) are used to indicate which columns in the DataView can be used as the *output* of the custom mapping action. Note that the name of the property `Features` is determined by the TensorFlow model. You cannot change this property name. diff --git a/docs/machine-learning/tutorials/time-series-demand-forecasting.md b/docs/machine-learning/tutorials/time-series-demand-forecasting.md index ecb7cf7bfee47..41ef44eab1f21 100644 --- a/docs/machine-learning/tutorials/time-series-demand-forecasting.md +++ b/docs/machine-learning/tutorials/time-series-demand-forecasting.md @@ -29,7 +29,7 @@ In this tutorial, you learn how to: ## Time series forecasting sample overview -This sample is a **C# .NET Core console application** that forecasts demand for bike rentals using a univariate time series analysis algorithm known as Singular Spectrum Analysis. The code for this sample can be found on the [dotnet/machinelearning-samples](https://github.com/dotnet/machinelearning-samples/tree/main/samples/csharp/getting-started/Forecasting_BikeSharingDemand) repository on GitHub. +This sample is a **C# console application** that forecasts demand for bike rentals using a univariate time series analysis algorithm known as Singular Spectrum Analysis. The code for this sample can be found on the [dotnet/machinelearning-samples](https://github.com/dotnet/machinelearning-samples/tree/main/samples/csharp/getting-started/Forecasting_BikeSharingDemand) repository on GitHub. ## Understand the problem diff --git a/docs/machine-learning/whats-new/overview.md b/docs/machine-learning/whats-new/overview.md new file mode 100644 index 0000000000000..26ca97880e577 --- /dev/null +++ b/docs/machine-learning/whats-new/overview.md @@ -0,0 +1,53 @@ +--- +title: What's new in ML.NET +titleSuffix: "" +description: Discover what's new in ML.NET. +ms.date: 04/15/2024 +ms.topic: whats-new + +#Customer intent: As a developer, I want to know what the new features are in ML.NET. + +--- + +# What's new in ML.NET + +> [!NOTE] +> This article is a work in progress. + +You can find all of the release notes for the ML.NET API in the [dotnet/machinelearning repo](https://github.com/dotnet/machinelearning/tree/main/docs/release-notes). + +## New deep-learning tasks + +ML.NET 3.0 added support for the following deep-learning tasks: + +- Object detection (backed by TorchSharp) +- Named entity recognition (NER) +- Question answering (QA) + +These trainers are included in the [Microsoft.ML.TorchSharp](https://www.nuget.org/packages/Microsoft.ML.TorchSharp) package. For more information, see [Announcing ML.NET 3.0](https://devblogs.microsoft.com/dotnet/announcing-ml-net-3-0/). + +## AutoML + +In ML.NET 3.0, the AutoML sweeper was updated to support the sentence similarity, question answering, and object detection tasks. For more information about AutoML, see [How to use the ML.NET Automated Machine Learning (AutoML) API](../how-to-guides/how-to-use-the-automl-api.md). + +## Additional tokenizer support + +[Microsoft.ML.Tokenizers](https://devblogs.microsoft.com/dotnet/announcing-ml-net-2-0/#tokenizer-support) is an open-source, cross-platform tokenization library. When it was introduced, the library was scoped to the [Byte-Pair Encoding (BPE)](https://en.wikipedia.org/wiki/Byte_pair_encoding) tokenization strategy to satisfy the language set of scenarios in ML.NET. Version 4.0 Preview 1 added support for the `Tiktoken` tokenizer. + +The following examples show how to use the `Tiktoken` text tokenizer. + +:::code language="csharp" source="./snippets/csharp/Tiktoken.cs" id="Tiktoken"::: + +### About tokenization + +Tokenization is a fundamental component in the preprocessing of natural language text for AI models. Tokenizers are responsible for breaking down a string of text into smaller, more manageable parts, often referred to as *tokens*. When using services like Azure OpenAI, you can use tokenizers to get a better understanding of cost and manage context. When working with self-hosted or local models, tokens are the inputs provided to those models. + +## Model Builder (Visual Studio extension) + +Model Builder has been updated to consume the ML.NET 3.0 release. Model Builder version 17.18.0 added question answering (QA) and named entity recognition (NER) scenarios. + +You can find all of the Model Builder release notes in the [dotnet/machinelearning-modelbuilder repo](https://github.com/dotnet/machinelearning-modelbuilder/tree/main/docs/release-notes). + +## See also + +- [Blog post: Announcing ML.NET 3.0](https://devblogs.microsoft.com/dotnet/announcing-ml-net-3-0/) diff --git a/docs/machine-learning/whats-new/snippets/csharp/Program.cs b/docs/machine-learning/whats-new/snippets/csharp/Program.cs new file mode 100644 index 0000000000000..194971ae32a1e --- /dev/null +++ b/docs/machine-learning/whats-new/snippets/csharp/Program.cs @@ -0,0 +1 @@ +TiktokenExample.RunIt(); diff --git a/docs/machine-learning/whats-new/snippets/csharp/Project.csproj b/docs/machine-learning/whats-new/snippets/csharp/Project.csproj new file mode 100644 index 0000000000000..57fd414b97dfb --- /dev/null +++ b/docs/machine-learning/whats-new/snippets/csharp/Project.csproj @@ -0,0 +1,13 @@ + + + + Exe + net9 + enable + + + + + + + diff --git a/docs/machine-learning/whats-new/snippets/csharp/Tiktoken.cs b/docs/machine-learning/whats-new/snippets/csharp/Tiktoken.cs new file mode 100644 index 0000000000000..5d26d83c6de9e --- /dev/null +++ b/docs/machine-learning/whats-new/snippets/csharp/Tiktoken.cs @@ -0,0 +1,65 @@ +using System; +using System.Collections.Generic; +using Microsoft.ML.Tokenizers; + +internal class TiktokenExample +{ + public static void RunIt() + { + // + Tokenizer tokenizer = Tokenizer.CreateTiktokenForModel("gpt-4"); + string text = "Hello, World!"; + + // Encode to IDs. + IReadOnlyList encodedIds = tokenizer.EncodeToIds(text); + Console.WriteLine($"encodedIds = {{{string.Join(", ", encodedIds)}}}"); + // encodedIds = {9906, 11, 4435, 0} + + // Decode IDs to text. + string? decodedText = tokenizer.Decode(encodedIds); + Console.WriteLine($"decodedText = {decodedText}"); + // decodedText = Hello, World! + + // Get token count. + int idsCount = tokenizer.CountTokens(text); + Console.WriteLine($"idsCount = {idsCount}"); + // idsCount = 4 + + // Full encoding. + EncodingResult result = tokenizer.Encode(text); + Console.WriteLine($"result.Tokens = {{'{string.Join("', '", result.Tokens)}'}}"); + // result.Tokens = {'Hello', ',', ' World', '!'} + Console.WriteLine($"result.Offsets = {{{string.Join(", ", result.Offsets)}}}"); + // result.Offsets = {(0, 5), (5, 1), (6, 6), (12, 1)} + Console.WriteLine($"result.Ids = {{{string.Join(", ", result.Ids)}}}"); + // result.Ids = {9906, 11, 4435, 0} + + // Encode up to number of tokens limit. + int index1 = tokenizer.IndexOfTokenCount( + text, + maxTokenCount: 1, + out string processedText1, + out int tokenCount1 + ); // Encode up to one token. + Console.WriteLine($"processedText1 = {processedText1}"); + // processedText1 = Hello, World! + Console.WriteLine($"tokenCount1 = {tokenCount1}"); + // tokenCount1 = 1 + Console.WriteLine($"index1 = {index1}"); + // index1 = 5 + + int index2 = tokenizer.LastIndexOfTokenCount( + text, + maxTokenCount: 1, + out string processedText2, + out int tokenCount2 + ); // Encode from end up to one token. + Console.WriteLine($"processedText2 = {processedText2}"); + // processedText2 = Hello, World! + Console.WriteLine($"tokenCount2 = {tokenCount2}"); + // tokenCount2 = 1 + Console.WriteLine($"index2 = {index2}"); + // index2 = 12 + // + } +} diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 20f8efdf6e734..0483f104ae58a 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -170,6 +170,8 @@ items: href: ../../core/tools/dotnet-nuget-sign.md - name: dotnet pack href: ../../core/tools/dotnet-pack.md + - name: dotnet package search + href: ../../core/tools/dotnet-package-search.md - name: dotnet publish href: ../../core/tools/dotnet-publish.md - name: dotnet restore diff --git a/docs/orleans/grains/index.md b/docs/orleans/grains/index.md index fc8fdc71b0a94..06449599291a3 100644 --- a/docs/orleans/grains/index.md +++ b/docs/orleans/grains/index.md @@ -219,11 +219,11 @@ await joinedTask; When a grain method throws an exception, Orleans propagates that exception up the calling stack, across hosts as necessary. For this to work as intended, exceptions must be serializable by Orleans and hosts which are handling the exception must have the exception type available. If an exception type isn't available, the exception will be thrown as an instance of , preserving the message, type, and stack trace of the original exception. -Exeptions thrown from grain methods don't cause the grain to be deactivated unless the exception inherits from . `InconsistentStateException` is thrown by storage operations which discover that the grain's in-memory state is inconsistent with the state in the database. Aside from the special-casing of `InconsistentStateException, this behavior is similar to throwing an exception from any .NET object: exceptions don't cause an object to be destroyed. +Exeptions thrown from grain methods don't cause the grain to be deactivated unless the exception inherits from . `InconsistentStateException` is thrown by storage operations which discover that the grain's in-memory state is inconsistent with the state in the database. Aside from the special-casing of `InconsistentStateException`, this behavior is similar to throwing an exception from any .NET object: exceptions don't cause an object to be destroyed. ### Virtual methods -A grain class can optionally override and virtual methods; are invoked by the Orleans runtime upon activation and deactivation of each grain of the class. This gives the grain code a chance to perform additional initialization and cleanup operations. An exception thrown by `OnActivateAsync` fails the activation process. +A grain class can optionally override the and virtual methods; these methods are invoked by the Orleans runtime upon activation and deactivation of each grain of the class. This gives the grain code a chance to perform additional initialization and cleanup operations. An exception thrown by `OnActivateAsync` fails the activation process. While `OnActivateAsync`, if overridden, is always called as part of the grain activation process, `OnDeactivateAsync` is not guaranteed to get called in all situations, for example, in case of a server failure or other abnormal event. Because of that, applications should not rely on `OnDeactivateAsync` for performing critical operations such as the persistence of state changes. They should use it only for best-effort operations. diff --git a/docs/orleans/overview.md b/docs/orleans/overview.md index 49efb86562e6b..cc18f6d467195 100644 --- a/docs/orleans/overview.md +++ b/docs/orleans/overview.md @@ -65,7 +65,7 @@ Orleans provides a simple persistence model that ensures the state is available While a grain is running, the state is kept in memory so that read requests can be served without accessing storage. When the grain updates its state, calling ensures that the backing store is updated for durability and consistency. -For more information, see the [Grain persistence](grains/grain-persistence/index.md). +For more information, see [Grain persistence](grains/grain-persistence/index.md). ### Timers and reminders diff --git a/docs/orleans/quickstarts/build-your-first-orleans-app.md b/docs/orleans/quickstarts/build-your-first-orleans-app.md index 507221ac51b46..549ad6554ea49 100644 --- a/docs/orleans/quickstarts/build-your-first-orleans-app.md +++ b/docs/orleans/quickstarts/build-your-first-orleans-app.md @@ -47,7 +47,7 @@ At the end of the quickstart, you have an app that creates and handles redirects 1. Inside Visual Studio Code, open the [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal). -1. Change directories (`cd`) directory that will contain the project. +1. Change to the directory (`cd`) that will contain the project. 1. Run the following commands: ```dotnetcli diff --git a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj index 52c42b93dc6f9..73254a23d4b63 100644 --- a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj +++ b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj @@ -12,7 +12,7 @@ - + diff --git a/docs/standard/assembly/contents.md b/docs/standard/assembly/contents.md index a0e23288ac81a..4dfb83d1d09e4 100644 --- a/docs/standard/assembly/contents.md +++ b/docs/standard/assembly/contents.md @@ -1,8 +1,8 @@ --- title: Assembly contents -description: This article describes the contents of a .NET assembly, which can include assembly metadata, type metadata, MSIL code, and resources. +description: This article describes the contents of a .NET assembly, which can include assembly metadata, type metadata, CIL code, and resources. ms.date: "08/20/2019" -helpviewer_keywords: +helpviewer_keywords: - "assemblies [.NET Framework]" - "assemblies [.NET Core]" - "single-file assemblies" @@ -16,7 +16,7 @@ In general, a static assembly can consist of four elements: - Type metadata. -- Microsoft intermediate language (MSIL) code that implements the types. It is generated by the compiler from one or more source code files. +- Common intermediate language (CIL) code that implements the types. It is generated by the compiler from one or more source code files. - A set of [resources](../../core/extensions/resources.md). diff --git a/docs/standard/assembly/identify.md b/docs/standard/assembly/identify.md index ffb1cfa9bed46..4125f0ade5b27 100644 --- a/docs/standard/assembly/identify.md +++ b/docs/standard/assembly/identify.md @@ -3,37 +3,36 @@ title: "How to: Determine if a file is an assembly" description: This article shows you how determine whether a file is a .NET assembly, both manually and programmatically. ms.date: 07/24/2021 ms.topic: how-to -dev_langs: +dev_langs: - "csharp" - "vb" --- # How to: Determine if a file is an assembly -A file is an assembly if and only if it is managed, and contains an assembly entry in its metadata. For more information on assemblies and metadata, see [Assembly manifest](manifest.md). - -## How to manually determine if a file is an assembly - -1. Start the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md). - -2. Load the file you want to test. - -3. If **ILDASM** reports that the file is not a portable executable (PE) file, then it is not an assembly. For more information, see the topic [How to: View assembly contents](view-contents.md). - -## How to programmatically determine if a file is an assembly +A file is an assembly if and only if it is managed, and contains an assembly entry in its metadata. For more information on assemblies and metadata, see [Assembly manifest](manifest.md). + +## How to manually determine if a file is an assembly + +1. Start the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) tool. + +2. Load the file you want to test. + +3. If **ILDASM** reports that the file is not a portable executable (PE) file, then it is not an assembly. For more information, see the topic [How to: View assembly contents](view-contents.md). + +## How to programmatically determine if a file is an assembly ### Using the AssemblyName class -1. Call the method, passing the full file path and name of the file you are testing. - -2. If a exception is thrown, the file is not an assembly. +1. Call the method, passing the full file path and name of the file you are testing. -This example tests a DLL to see if it is an assembly. +2. If a exception is thrown, the file is not an assembly. -[!code-csharp[](snippets/identify/csharp/ExampleAssemblyName.cs#AssemblyName)] +This example tests a DLL to see if it is an assembly. +[!code-csharp[](snippets/identify/csharp/ExampleAssemblyName.cs#AssemblyName)] [!code-vb[](snippets/identify/visual-basic/ExampleAssemblyName.vb#AssemblyName)] -The method loads the test file, and then releases it once the information is read. +The method loads the test file, and then releases it once the information is read. ### Using the PEReader class @@ -54,7 +53,6 @@ Unlike the method, the This example shows how to determine if a file is an assembly using the class. [!code-csharp[](snippets/identify/csharp/ExamplePeReader.cs#PeReader)] - [!code-vb[](snippets/identify/visual-basic/ExamplePeReader.vb#PeReader)] ## See also diff --git a/docs/standard/assembly/index.md b/docs/standard/assembly/index.md index c2cfe1b6444a6..6a201aee40e4b 100644 --- a/docs/standard/assembly/index.md +++ b/docs/standard/assembly/index.md @@ -46,7 +46,7 @@ An assembly defines the following information: - The **type boundary**. Every type's identity includes the name of the assembly in which it resides. A type called `MyType` that's loaded in the scope of one assembly isn't the same as a type called `MyType` that's loaded in the scope of another assembly. -- The **reference-scope boundary**: The [assembly manifest](#assembly-manifest) has metadata that's used for resolving types and satisfying resource requests. The manifest specifies the types and resources to expose outside the assembly and enumerates other assemblies on which it depends. Microsoft intermediate language (MSIL) code in a portable executable (PE) file won't be executed unless it has an associated [assembly manifest](#assembly-manifest). +- The **reference-scope boundary**: The [assembly manifest](#assembly-manifest) has metadata that's used for resolving types and satisfying resource requests. The manifest specifies the types and resources to expose outside the assembly and enumerates other assemblies on which it depends. Common intermediate language (CIL) code in a portable executable (PE) file won't be executed unless it has an associated [assembly manifest](#assembly-manifest). - The **version boundary**. The assembly is the smallest versionable unit in the common language runtime. All types and resources in the same assembly are versioned as a unit. The [assembly manifest](#assembly-manifest) describes the version dependencies you specify for any dependent assemblies. For more information about versioning, see [Assembly versioning](versioning.md). diff --git a/docs/standard/assembly/manifest.md b/docs/standard/assembly/manifest.md index 3a68452f42a22..9d94f660debfb 100644 --- a/docs/standard/assembly/manifest.md +++ b/docs/standard/assembly/manifest.md @@ -2,7 +2,7 @@ title: "Assembly manifest" description: A .NET assembly manifest specifies its version requirements, security identity, and scope of the assembly and information to resolve references. ms.date: "08/20/2019" -helpviewer_keywords: +helpviewer_keywords: - "assembly manifest" - "dynamic assemblies, assembly manifest" - "metadata, assembly manifest" @@ -12,42 +12,42 @@ ms.assetid: 8e40fab9-549d-4731-aec2-ffa47a382de0 --- # Assembly manifest -Every assembly, whether static or dynamic, contains a collection of data that describes how the elements in the assembly relate to each other. The assembly manifest contains this assembly metadata. An assembly manifest contains all the metadata needed to specify the assembly's version requirements and security identity, and all metadata needed to define the scope of the assembly and resolve references to resources and classes. The assembly manifest can be stored in either a PE file (an *.exe* or *.dll*) with Microsoft intermediate language (MSIL) code or in a standalone PE file that contains only assembly manifest information. - - The following illustration shows the different ways the manifest can be stored. - - ![Diagram that shows the manifest in a single-file assembly and multifile assembly configuration.](./media/manifest/assembly-types-diagram.gif) - - For an assembly with one associated file, the manifest is incorporated into the PE file to form a single-file assembly. You can create a multifile assembly with a standalone manifest file or with the manifest incorporated into one of the PE files in the assembly. - - Each assembly's manifest performs the following functions: - -- Enumerates the files that make up the assembly. - -- Governs how references to the assembly's types and resources map to the files that contain their declarations and implementations. - -- Enumerates other assemblies on which the assembly depends. - -- Provides a level of indirection between consumers of the assembly and the assembly's implementation details. - -- Renders the assembly self-describing. - -## Assembly manifest contents - - The following table shows the information contained in the assembly manifest. The first four items: assembly name, version number, culture, and strong name information make up the assembly's identity. - -|Information|Description| -|-----------------|-----------------| -|Assembly name|A text string specifying the assembly's name.| -|Version number|A major and minor version number, and a revision and build number. The common language runtime uses these numbers to enforce version policy.| -|Culture|Information on the culture or language the assembly supports. This information should be used only to designate an assembly as a satellite assembly containing culture- or language-specific information. (An assembly with culture information is automatically assumed to be a satellite assembly.)| -|Strong name information|The public key from the publisher if the assembly has been given a strong name.| -|List of all files in the assembly|A hash of each file contained in the assembly and a file name. Note that all files that make up the assembly must be in the same directory as the file containing the assembly manifest.| -|Type reference information|Information used by the runtime to map a type reference to the file that contains its declaration and implementation. This is used for types that are exported from the assembly.| -|Information on referenced assemblies|A list of other assemblies that are statically referenced by the assembly. Each reference includes the dependent assembly's name, assembly metadata (version, culture, operating system, and so on), and public key, if the assembly is strong named.| - - You can add or change some information in the assembly manifest by using assembly attributes in your code. You can change version information and informational attributes, including Trademark, Copyright, Product, Company, and Informational Version. For a complete list of assembly attributes, see [Set assembly attributes](set-attributes.md). - +Every assembly, whether static or dynamic, contains a collection of data that describes how the elements in the assembly relate to each other. The assembly manifest contains this assembly metadata. An assembly manifest contains all the metadata needed to specify the assembly's version requirements and security identity, and all metadata needed to define the scope of the assembly and resolve references to resources and classes. The assembly manifest can be stored in either a PE file (an *.exe* or *.dll*) with common intermediate language (CIL) code or in a standalone PE file that contains only assembly manifest information. + + The following illustration shows the different ways the manifest can be stored. + + ![Diagram that shows the manifest in a single-file assembly and multifile assembly configuration.](./media/manifest/assembly-types-diagram.gif) + + For an assembly with one associated file, the manifest is incorporated into the PE file to form a single-file assembly. You can create a multifile assembly with a standalone manifest file or with the manifest incorporated into one of the PE files in the assembly. + + Each assembly's manifest performs the following functions: + +- Enumerates the files that make up the assembly. + +- Governs how references to the assembly's types and resources map to the files that contain their declarations and implementations. + +- Enumerates other assemblies on which the assembly depends. + +- Provides a level of indirection between consumers of the assembly and the assembly's implementation details. + +- Renders the assembly self-describing. + +## Assembly manifest contents + + The following table shows the information contained in the assembly manifest. The first four items: assembly name, version number, culture, and strong name information make up the assembly's identity. + +|Information|Description| +|-----------------|-----------------| +|Assembly name|A text string specifying the assembly's name.| +|Version number|A major and minor version number, and a revision and build number. The common language runtime uses these numbers to enforce version policy.| +|Culture|Information on the culture or language the assembly supports. This information should be used only to designate an assembly as a satellite assembly containing culture- or language-specific information. (An assembly with culture information is automatically assumed to be a satellite assembly.)| +|Strong name information|The public key from the publisher if the assembly has been given a strong name.| +|List of all files in the assembly|A hash of each file contained in the assembly and a file name. Note that all files that make up the assembly must be in the same directory as the file containing the assembly manifest.| +|Type reference information|Information used by the runtime to map a type reference to the file that contains its declaration and implementation. This is used for types that are exported from the assembly.| +|Information on referenced assemblies|A list of other assemblies that are statically referenced by the assembly. Each reference includes the dependent assembly's name, assembly metadata (version, culture, operating system, and so on), and public key, if the assembly is strong named.| + + You can add or change some information in the assembly manifest by using assembly attributes in your code. You can change version information and informational attributes, including Trademark, Copyright, Product, Company, and Informational Version. For a complete list of assembly attributes, see [Set assembly attributes](set-attributes.md). + ## See also - [Assembly contents](contents.md) diff --git a/docs/standard/assembly/view-contents.md b/docs/standard/assembly/view-contents.md index a1aa615047270..ad4b040cdb025 100644 --- a/docs/standard/assembly/view-contents.md +++ b/docs/standard/assembly/view-contents.md @@ -18,7 +18,7 @@ dev_langs: --- # How to: View assembly contents -You can use the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) to view Microsoft intermediate language (MSIL) information in a file. If the file being examined is an assembly, this information can include the assembly's attributes and references to other modules and assemblies. This information can be helpful in determining whether a file is an assembly or part of an assembly and whether the file has references to other modules or assemblies. +You can use the [Ildasm.exe (IL Disassembler)](../../framework/tools/ildasm-exe-il-disassembler.md) to view common intermediate language (CIL) information in a file. If the file being examined is an assembly, this information can include the assembly's attributes and references to other modules and assemblies. This information can be helpful in determining whether a file is an assembly or part of an assembly and whether the file has references to other modules or assemblies. To display the contents of an assembly using *Ildasm.exe*, enter **ildasm \** at a command prompt. For example, the following command disassembles the *Hello.exe* assembly. @@ -26,7 +26,7 @@ To display the contents of an assembly using *Ildasm.exe*, enter **ildasm \. +The common language runtime allows you to add keyword-like descriptive declarations, called attributes, to annotate programming elements such as types, fields, methods, and properties. When you compile your code for the runtime, it is converted into common intermediate language (CIL) and placed inside a portable executable (PE) file along with metadata generated by the compiler. Attributes allow you to place extra descriptive information into metadata that can be extracted using runtime reflection services. The compiler creates attributes when you declare instances of special classes that derive from . .NET uses attributes for a variety of reasons and to address a number of issues. Attributes describe how to serialize data, specify characteristics that are used to enforce security, and limit optimizations by the just-in-time (JIT) compiler so the code remains easy to debug. Attributes can also record the name of a file or the author of code, or control the visibility of controls and members during forms development. diff --git a/docs/standard/base-types/best-practices-regex.md b/docs/standard/base-types/best-practices-regex.md index bb0b741aee6e5..7526ebd9f5b13 100644 --- a/docs/standard/base-types/best-practices-regex.md +++ b/docs/standard/base-types/best-practices-regex.md @@ -76,7 +76,7 @@ The particular way in which you call regular expression matching methods can aff ### Static regular expressions -Static regular expression methods are recommended as an alternative to repeatedly instantiating a regular expression object with the same regular expression. Unlike regular expression patterns used by regular expression objects, either the operation codes or the compiled Microsoft intermediate language (MSIL) from patterns used in static method calls is cached internally by the regular expression engine. +Static regular expression methods are recommended as an alternative to repeatedly instantiating a regular expression object with the same regular expression. Unlike regular expression patterns used by regular expression objects, either the operation codes or the compiled common intermediate language (CIL) from patterns used in static method calls is cached internally by the regular expression engine. For example, an event handler frequently calls another method to validate user input. This example is reflected in the following code, in which a control's event is used to call a method named `IsValidCurrency`, which checks whether the user has entered a currency symbol followed by at least one decimal digit. @@ -108,9 +108,9 @@ The regular expression `\p{Sc}+\s*\d+` that's used in this example verifies that ### Interpreted vs. compiled regular expressions -Regular expression patterns that aren't bound to the regular expression engine through the specification of the option are interpreted. When a regular expression object is instantiated, the regular expression engine converts the regular expression to a set of operation codes. When an instance method is called, the operation codes are converted to MSIL and executed by the JIT compiler. Similarly, when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to a set of operation codes and stores them in the cache. It then converts these operation codes to MSIL so that the JIT compiler can execute them. Interpreted regular expressions reduce startup time at the cost of slower execution time. Because of this process, they're best used when the regular expression is used in a small number of method calls, or if the exact number of calls to regular expression methods is unknown but is expected to be small. As the number of method calls increases, the performance gain from reduced startup time is outstripped by the slower execution speed. +Regular expression patterns that aren't bound to the regular expression engine through the specification of the option are interpreted. When a regular expression object is instantiated, the regular expression engine converts the regular expression to a set of operation codes. When an instance method is called, the operation codes are converted to CIL and executed by the JIT compiler. Similarly, when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to a set of operation codes and stores them in the cache. It then converts these operation codes to CIL so that the JIT compiler can execute them. Interpreted regular expressions reduce startup time at the cost of slower execution time. Because of this process, they're best used when the regular expression is used in a small number of method calls, or if the exact number of calls to regular expression methods is unknown but is expected to be small. As the number of method calls increases, the performance gain from reduced startup time is outstripped by the slower execution speed. -Regular expression patterns that are bound to the regular expression engine through the specification of the option are compiled. Therefore, when a regular expression object is instantiated, or when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to an intermediary set of operation codes. These codes are then converted to MSIL. When a method is called, the JIT compiler executes the MSIL. In contrast to interpreted regular expressions, compiled regular expressions increase startup time but execute individual pattern-matching methods faster. As a result, the performance benefit that results from compiling the regular expression increases in proportion to the number of regular expression methods called. +Regular expression patterns that are bound to the regular expression engine through the specification of the option are compiled. Therefore, when a regular expression object is instantiated, or when a static regular expression method is called and the regular expression can't be found in the cache, the regular expression engine converts the regular expression to an intermediary set of operation codes. These codes are then converted to CIL. When a method is called, the JIT compiler executes the CIL. In contrast to interpreted regular expressions, compiled regular expressions increase startup time but execute individual pattern-matching methods faster. As a result, the performance benefit that results from compiling the regular expression increases in proportion to the number of regular expression methods called. To summarize, we recommend that you use interpreted regular expressions when you call regular expression methods with a specific regular expression relatively infrequently. You should use compiled regular expressions when you call regular expression methods with a specific regular expression relatively frequently. It's difficult to determine the exact threshold at which the slower execution speeds of interpreted regular expressions outweigh gains from their reduced startup time, or the threshold at which the slower startup times of compiled regular expressions outweigh gains from their faster execution speeds. It depends on various factors, including the complexity of the regular expression and the specific data that it processes. To determine whether interpreted or compiled regular expressions offer the best performance for your particular application scenario, you can use the class to compare their execution times. diff --git a/docs/standard/base-types/character-encoding-introduction.md b/docs/standard/base-types/character-encoding-introduction.md index d8033ac8bc579..33570508cb81f 100644 --- a/docs/standard/base-types/character-encoding-introduction.md +++ b/docs/standard/base-types/character-encoding-introduction.md @@ -265,7 +265,7 @@ In .NET APIs, a grapheme cluster is called a *text element*. The following metho :::code language="csharp" source="snippets/character-encoding-introduction/csharp/CountTextElements.cs" id="SnippetCallCountMethod"::: -If you run this code in .NET Framework or .NET Core 3.1 or earlier, the text element count for the emoji shows `4`. That is due to a bug in the `StringInfo` class that is fixed in .NET 5. +If you run this code in .NET Framework or .NET Core 3.1 or earlier, the text element count for the emoji shows `4`. That is due to a bug in the `StringInfo` class that was fixed in .NET 5. ### Example: splitting string instances diff --git a/docs/standard/base-types/common-type-system.md b/docs/standard/base-types/common-type-system.md index e088be594ed5f..3abdb4d940c40 100644 --- a/docs/standard/base-types/common-type-system.md +++ b/docs/standard/base-types/common-type-system.md @@ -228,7 +228,7 @@ A property names a value or state of the type and defines methods for getting or [!code-csharp[Conceptual.Types.Members.Properties#1](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.types.members.properties/cs/example.cs#1)] [!code-vb[Conceptual.Types.Members.Properties#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.types.members.properties/vb/example.vb#1)] -In addition to including the property itself, the Microsoft intermediate language (MSIL) for a type that contains a readable property includes a `get_`*propertyname* method, and the MSIL for a type that contains a writable property includes a `set_`*propertyname* method. +In addition to including the property itself, the common intermediate language (CIL) for a type that contains a readable property includes a `get_`*propertyname* method, and the CIL for a type that contains a writable property includes a `set_`*propertyname* method. ### Methods diff --git a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md index cf01c8f254dc5..a0dec2ad85f23 100644 --- a/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md +++ b/docs/standard/base-types/compilation-and-reuse-in-regular-expressions.md @@ -3,7 +3,7 @@ title: "Compilation and Reuse in Regular Expressions" description: "Learn about compilation and reuse in Regular Expressions." ms.topic: conceptual ms.date: "03/30/2017" -helpviewer_keywords: +helpviewer_keywords: - "parsing text with regular expressions, compilation" - "searching with regular expressions, compilation" - ".NET regular expressions, engines" @@ -16,30 +16,30 @@ ms.assetid: 182ec76d-5a01-4d73-996c-0b0d14fcea18 --- # Compilation and Reuse in Regular Expressions -You can optimize the performance of applications that make extensive use of regular expressions by understanding how the regular expression engine compiles expressions and by understanding how regular expressions are cached. This topic discusses both compilation and caching. - -## Compiled Regular Expressions +You can optimize the performance of applications that make extensive use of regular expressions by understanding how the regular expression engine compiles expressions and by understanding how regular expressions are cached. This topic discusses both compilation and caching. - By default, the regular expression engine compiles a regular expression to a sequence of internal instructions (these are high-level codes that are different from Microsoft intermediate language, or MSIL). When the engine executes a regular expression, it interprets the internal codes. - - If a object is constructed with the option, it compiles the regular expression to explicit MSIL code instead of high-level regular expression internal instructions. This allows .NET's just-in-time (JIT) compiler to convert the expression to native machine code for higher performance. The cost of constructing the object may be higher, but the cost of performing matches with it is likely to be much smaller. +## Compiled Regular Expressions - An alternative is to use precompiled regular expressions. You can compile all of your expressions into a reusable DLL by using the method. This avoids the need to compile at run time while still benefiting from the speed of compiled regular expressions. - -## The Regular Expressions Cache + By default, the regular expression engine compiles a regular expression to a sequence of internal instructions (these are high-level codes that are different from common intermediate language, or CIL). When the engine executes a regular expression, it interprets the internal codes. + + If a object is constructed with the option, it compiles the regular expression to explicit CIL code instead of high-level regular expression internal instructions. This allows .NET's just-in-time (JIT) compiler to convert the expression to native machine code for higher performance. The cost of constructing the object may be higher, but the cost of performing matches with it is likely to be much smaller. + + An alternative is to use precompiled regular expressions. You can compile all of your expressions into a reusable DLL by using the method. This avoids the need to compile at run time while still benefiting from the speed of compiled regular expressions. + +## The Regular Expressions Cache + + To improve performance, the regular expression engine maintains an application-wide cache of compiled regular expressions. The cache stores regular expression patterns that are used only in static method calls. (Regular expression patterns supplied to instance methods are not cached.) This avoids the need to reparse an expression into high-level byte code each time it is used. + + The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. + + Your application can reuse regular expressions in one of the following two ways: - To improve performance, the regular expression engine maintains an application-wide cache of compiled regular expressions. The cache stores regular expression patterns that are used only in static method calls. (Regular expression patterns supplied to instance methods are not cached.) This avoids the need to reparse an expression into high-level byte code each time it is used. - - The maximum number of cached regular expressions is determined by the value of the `static` (`Shared` in Visual Basic) property. By default, the regular expression engine caches up to 15 compiled regular expressions. If the number of compiled regular expressions exceeds the cache size, the least recently used regular expression is discarded and the new regular expression is cached. - - Your application can reuse regular expressions in one of the following two ways: - - By using a static method of the object to define the regular expression. If you're using a regular expression pattern that has already been defined by another static method call, the regular expression engine will try to retrieve it from the cache. If it's not available in the cache, the engine will compile the regular expression and add it to the cache. - -- By reusing an existing object as long as its regular expression pattern is needed. - - Because of the overhead of object instantiation and regular expression compilation, creating and rapidly destroying numerous objects is a very expensive process. For applications that use a large number of different regular expressions, you can optimize performance by using calls to static `Regex` methods and possibly by increasing the size of the regular expression cache. - + +- By reusing an existing object as long as its regular expression pattern is needed. + + Because of the overhead of object instantiation and regular expression compilation, creating and rapidly destroying numerous objects is a very expensive process. For applications that use a large number of different regular expressions, you can optimize performance by using calls to static `Regex` methods and possibly by increasing the size of the regular expression cache. + ## See also - [.NET Regular Expressions](regular-expressions.md) diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index 34b9fcb164a2d..d6c0114499668 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -230,7 +230,7 @@ Finally, you can use the inline group element `(?n:)` to suppress automatic capt By default, regular expressions in .NET are interpreted. When a object is instantiated or a static method is called, the regular expression pattern is parsed into a set of custom opcodes, and an interpreter uses these opcodes to run the regular expression. This involves a tradeoff: The cost of initializing the regular expression engine is minimized at the expense of run-time performance. -You can use compiled instead of interpreted regular expressions by using the option. In this case, when a pattern is passed to the regular expression engine, it is parsed into a set of opcodes and then converted to Microsoft intermediate language (MSIL), which can be passed directly to the common language runtime. Compiled regular expressions maximize run-time performance at the expense of initialization time. +You can use compiled instead of interpreted regular expressions by using the option. In this case, when a pattern is passed to the regular expression engine, it is parsed into a set of opcodes and then converted to common intermediate language (CIL), which can be passed directly to the common language runtime. Compiled regular expressions maximize run-time performance at the expense of initialization time. > [!NOTE] > A regular expression can be compiled only by supplying the value to the `options` parameter of a class constructor or a static pattern-matching method. It is not available as an inline option. diff --git a/docs/standard/collections/commonly-used-collection-types.md b/docs/standard/collections/commonly-used-collection-types.md index a0614c95de3b8..292f77110cb44 100644 --- a/docs/standard/collections/commonly-used-collection-types.md +++ b/docs/standard/collections/commonly-used-collection-types.md @@ -70,7 +70,7 @@ The LINQ to Objects feature provides a common pattern for accessing in-memory ob - They can filter, order, and group data. - They can improve performance. -For more information, see [LINQ to Objects (C#)](../../csharp/linq/query-a-collection-of-objects.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). +For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). ## Related topics diff --git a/docs/standard/collections/index.md b/docs/standard/collections/index.md index 215b51c1975f7..dc9eeae9c95d5 100644 --- a/docs/standard/collections/index.md +++ b/docs/standard/collections/index.md @@ -29,7 +29,7 @@ All collections provide methods for adding, removing, or finding items in the co - **The ability to enumerate the collection** - .NET collections either implement or to enable the collection to be iterated through. An enumerator can be thought of as a movable pointer to any element in the collection. The [foreach, in](../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) statement and the [For Each...Next Statement](../../visual-basic/language-reference/statements/for-each-next-statement.md) use the enumerator exposed by the method and hide the complexity of manipulating the enumerator. In addition, any collection that implements is considered a *queryable type* and can be queried with LINQ. LINQ queries provide a common pattern for accessing data. They're typically more concise and readable than standard `foreach` loops and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/query-a-collection-of-objects.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md), [Introduction to LINQ Queries (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), and [Basic Query Operations (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/basic-query-operations.md). + .NET collections either implement or to enable the collection to be iterated through. An enumerator can be thought of as a movable pointer to any element in the collection. The [foreach, in](../../csharp/language-reference/statements/iteration-statements.md#the-foreach-statement) statement and the [For Each...Next Statement](../../visual-basic/language-reference/statements/for-each-next-statement.md) use the enumerator exposed by the method and hide the complexity of manipulating the enumerator. In addition, any collection that implements is considered a *queryable type* and can be queried with LINQ. LINQ queries provide a common pattern for accessing data. They're typically more concise and readable than standard `foreach` loops and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md), [Introduction to LINQ Queries (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), and [Basic Query Operations (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/basic-query-operations.md). - **The ability to copy the collection contents to an array** diff --git a/docs/standard/collections/selecting-a-collection-class.md b/docs/standard/collections/selecting-a-collection-class.md index efc7181de91b3..0459fb3fa23e5 100644 --- a/docs/standard/collections/selecting-a-collection-class.md +++ b/docs/standard/collections/selecting-a-collection-class.md @@ -73,7 +73,7 @@ Consider the following questions: ## LINQ to Objects and PLINQ -LINQ to Objects enables developers to use LINQ queries to access in-memory objects as long as the object type implements or . LINQ queries provide a common pattern for accessing data, are typically more concise and readable than standard `foreach` loops, and provide filtering, ordering, and grouping capabilities. For more information, see [LINQ to Objects (C#)](../../csharp/linq/query-a-collection-of-objects.md) and [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md). +LINQ to Objects enables developers to use LINQ queries to access in-memory objects as long as the object type implements or . LINQ queries provide a common pattern for accessing data, are typically more concise and readable than standard `foreach` loops, and provide filtering, ordering, and grouping capabilities. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md) and [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md). PLINQ provides a parallel implementation of LINQ to Objects that can offer faster query execution in many scenarios, through more efficient use of multi-core computers. For more information, see [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). diff --git a/docs/standard/collections/when-to-use-generic-collections.md b/docs/standard/collections/when-to-use-generic-collections.md index eabc3b1f2c4a3..278e75dfda3d4 100644 --- a/docs/standard/collections/when-to-use-generic-collections.md +++ b/docs/standard/collections/when-to-use-generic-collections.md @@ -55,7 +55,7 @@ The `Builder` object can be created by calling the nongeneric `CreateBuilder()` ## LINQ to Objects -The LINQ to Objects feature enables you to use LINQ queries to access in-memory objects as long as the object type implements the or interface. LINQ queries provide a common pattern for accessing data; are typically more concise and readable than standard `foreach` loops; and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/query-a-collection-of-objects.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). +The LINQ to Objects feature enables you to use LINQ queries to access in-memory objects as long as the object type implements the or interface. LINQ queries provide a common pattern for accessing data; are typically more concise and readable than standard `foreach` loops; and provide filtering, ordering, and grouping capabilities. LINQ queries can also improve performance. For more information, see [LINQ to Objects (C#)](../../csharp/linq/get-started/introduction-to-linq-queries.md), [LINQ to Objects (Visual Basic)](../../visual-basic/programming-guide/concepts/linq/linq-to-objects.md), and [Parallel LINQ (PLINQ)](../parallel-programming/introduction-to-plinq.md). ## Additional Functionality diff --git a/docs/standard/commandline/tab-completion.md b/docs/standard/commandline/tab-completion.md index eb39496416021..4336f7387418e 100644 --- a/docs/standard/commandline/tab-completion.md +++ b/docs/standard/commandline/tab-completion.md @@ -32,9 +32,9 @@ For other command-line apps built on `System.CommandLine`: * For `bash`, add the contents of [*dotnet-suggest-shim.bash*](https://github.com/dotnet/command-line-api/blob/main/src/System.CommandLine.Suggest/dotnet-suggest-shim.bash) to *~/.bash_profile*. - * For `zsh`, add the contents of [dotnet-suggest-shim.zsh](https://github.com/dotnet/command-line-api/blob/master/src/System.CommandLine.Suggest/dotnet-suggest-shim.zsh) to *~/.zshrc*. + * For `zsh`, add the contents of [dotnet-suggest-shim.zsh](https://github.com/dotnet/command-line-api/blob/main/src/System.CommandLine.Suggest/dotnet-suggest-shim.zsh) to *~/.zshrc*. - * For PowerShell, add the contents of [*dotnet-suggest-shim.ps1*](https://github.com/dotnet/command-line-api/blob/master/src/System.CommandLine.Suggest/dotnet-suggest-shim.ps1) to your PowerShell profile. You can find the expected path to your PowerShell profile by running the following command in your console: + * For PowerShell, add the contents of [*dotnet-suggest-shim.ps1*](https://github.com/dotnet/command-line-api/blob/main/src/System.CommandLine.Suggest/dotnet-suggest-shim.ps1) to your PowerShell profile. You can find the expected path to your PowerShell profile by running the following command in your console: ```console echo $profile diff --git a/docs/standard/data/xml/script-blocks-using-msxsl-script.md b/docs/standard/data/xml/script-blocks-using-msxsl-script.md index a29f728b6af06..ffe21e97d91ad 100644 --- a/docs/standard/data/xml/script-blocks-using-msxsl-script.md +++ b/docs/standard/data/xml/script-blocks-using-msxsl-script.md @@ -2,7 +2,7 @@ description: "Learn more about: Script Blocks Using msxsl:script" title: "Script Blocks Using msxsl:script" ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" ms.assetid: fde6f43f-c594-486f-abcb-2211197fae20 @@ -12,147 +12,147 @@ ms.assetid: fde6f43f-c594-486f-abcb-2211197fae20 > [!NOTE] > Script blocks are supported only in .NET Framework. They are _not_ supported on .NET Core or .NET 5 or later. -The class supports embedded scripts using the `msxsl:script` element. When the style sheet is loaded, any defined functions are compiled to Microsoft intermediate language (MSIL) by the Code Document Object Model (CodeDOM) and are executed during run time. The assembly generated from the embedded script block is separate than the assembly generated for the style sheet. - -## Enable XSLT Script +The class supports embedded scripts using the `msxsl:script` element. When the style sheet is loaded, any defined functions are compiled to common intermediate language (CIL) by the Code Document Object Model (CodeDOM) and are executed during run time. The assembly generated from the embedded script block is separate than the assembly generated for the style sheet. + +## Enable XSLT Script + + Support for embedded scripts is an optional XSLT setting on the class. Script support is disabled by default. To enable script support, create an object with the property set to `true` and pass the object to the method. - Support for embedded scripts is an optional XSLT setting on the class. Script support is disabled by default. To enable script support, create an object with the property set to `true` and pass the object to the method. - > [!NOTE] -> XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. - -## msxsl:script Element Definition - - The `msxsl:script` element is a Microsoft extension to the XSLT 1.0 recommendation and has the following definition: - -```xml - -``` - - The `msxsl` prefix is bound to the `urn:schemas-microsoft-com:xslt` namespace URI. The style sheet must include the `xmlns:msxsl=urn:schemas-microsoft-com:xslt` namespace declaration. - - The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. - - The `implements-prefix` attribute is mandatory. This attribute is used to declare a namespace and associate it with the script block. The value of this attribute is the prefix that represents the namespace. This prefix can be defined somewhere in a style sheet. - +> XSLT scripting should be enabled only if you require script support and you are working in a fully trusted environment. + +## msxsl:script Element Definition + + The `msxsl:script` element is a Microsoft extension to the XSLT 1.0 recommendation and has the following definition: + +```xml + +``` + + The `msxsl` prefix is bound to the `urn:schemas-microsoft-com:xslt` namespace URI. The style sheet must include the `xmlns:msxsl=urn:schemas-microsoft-com:xslt` namespace declaration. + + The `language` attribute is optional. Its value is the code language of the embedded code block. The language is mapped to the appropriate CodeDOM compiler using the method. The class can support any Microsoft .NET language, assuming the appropriate provider is installed on the machine and is registered in the system.codedom section of the machine.config file. If a `language` attribute is not specified, the language defaults to JScript. The language name is not case-sensitive so 'JavaScript' and 'javascript' are equivalent. + + The `implements-prefix` attribute is mandatory. This attribute is used to declare a namespace and associate it with the script block. The value of this attribute is the prefix that represents the namespace. This prefix can be defined somewhere in a style sheet. + > [!NOTE] -> When using the `msxsl:script` element, we strongly recommend that the script, regardless of language, be placed inside a CDATA section. Because the script can contain operators, identifiers, or delimiters for a given language, if it is not contained within a CDATA section, it has the potential of being misinterpreted as XML. The following XML shows a template of the CDATA section where code can be placed. - -```xml - - - -``` - -## Script Functions - - Functions can be declared within the `msxsl:script` element. When a function is declared, it is contained in a script block. Style sheets can contain multiple script blocks, each operating independent of the other. That means that if you are executing inside a script block, you cannot call a function that you defined in another script block unless it is declared to have the same namespace and the same scripting language. Because each script block can be in its own language, and the block is parsed according to the grammar rules of that language parser we recommend that you use the correct syntax for the language in use. For example, if you are in a Microsoft C# script block, use the C# comment syntax. - - The supplied arguments and return values to the function can be of any type. Because the W3C XPath types are a subset of the common language runtime (CLR) types, type conversion takes place on types that are not considered to be an XPath type. The following table shows the corresponding W3C types and the equivalent CLR type. - -|W3C type|CLR type| -|--------------|--------------| -|`String`|| -|`Boolean`|| -|`Number`|| -|`Result Tree Fragment`|| -|`Node Set`|| - - CLR numeric types are converted to . The type is converted to . types are converted to . **XPathNavigator[]** is converted to . - - All other types throw an error. - -### Importing Namespaces and Assemblies - - The class predefines a set of assemblies and namespaces that are supported by default by the `msxsl:script` element. However, you can use classes and members belonging to a namespace that is not on the predefined list by importing the assembly and namespace in `msxsl:script` block. - -#### Assemblies - - The following two assemblies are referenced by default: - -- System.dll - -- System.Xml.dll - -- Microsoft.VisualBasic.dll (when the script language is VB) - - You can import the additional assemblies using the `msxsl:assembly` element. This includes the assembly when the style sheet is compiled. The `msxsl:assembly` element has the following definition: - -```xml - - - - - -``` - - The `name` attribute contains the name of the assembly and the `href` attribute contains the path to the assembly. The assembly name can be a full name, such as "System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", or a short name, such as "System.Web". - -#### Namespaces - - The following namespaces are included by default: - -- System - -- System.Collection - -- System.Text - -- System.Text.RegularExpressions - -- System.Xml - -- System.Xml.Xsl - -- System.Xml.XPath - -- Microsoft.VisualBasic (when the script language is VB) - - You can add support for additional namespaces using the `namespace` attribute. The attribute value is the name of the namespace. - -```xml - - - - -``` - -## Example - - The following example uses an embedded script to calculate the circumference of a circle given its radius. - +> When using the `msxsl:script` element, we strongly recommend that the script, regardless of language, be placed inside a CDATA section. Because the script can contain operators, identifiers, or delimiters for a given language, if it is not contained within a CDATA section, it has the potential of being misinterpreted as XML. The following XML shows a template of the CDATA section where code can be placed. + +```xml + + + +``` + +## Script Functions + + Functions can be declared within the `msxsl:script` element. When a function is declared, it is contained in a script block. Style sheets can contain multiple script blocks, each operating independent of the other. That means that if you are executing inside a script block, you cannot call a function that you defined in another script block unless it is declared to have the same namespace and the same scripting language. Because each script block can be in its own language, and the block is parsed according to the grammar rules of that language parser we recommend that you use the correct syntax for the language in use. For example, if you are in a Microsoft C# script block, use the C# comment syntax. + + The supplied arguments and return values to the function can be of any type. Because the W3C XPath types are a subset of the common language runtime (CLR) types, type conversion takes place on types that are not considered to be an XPath type. The following table shows the corresponding W3C types and the equivalent CLR type. + +|W3C type|CLR type| +|--------------|--------------| +|`String`|| +|`Boolean`|| +|`Number`|| +|`Result Tree Fragment`|| +|`Node Set`|| + + CLR numeric types are converted to . The type is converted to . types are converted to . **XPathNavigator[]** is converted to . + + All other types throw an error. + +### Importing Namespaces and Assemblies + + The class predefines a set of assemblies and namespaces that are supported by default by the `msxsl:script` element. However, you can use classes and members belonging to a namespace that is not on the predefined list by importing the assembly and namespace in `msxsl:script` block. + +#### Assemblies + + The following two assemblies are referenced by default: + +- System.dll + +- System.Xml.dll + +- Microsoft.VisualBasic.dll (when the script language is VB) + + You can import the additional assemblies using the `msxsl:assembly` element. This includes the assembly when the style sheet is compiled. The `msxsl:assembly` element has the following definition: + +```xml + + + + + +``` + + The `name` attribute contains the name of the assembly and the `href` attribute contains the path to the assembly. The assembly name can be a full name, such as "System.Data, Version=2.0.3600.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", or a short name, such as "System.Web". + +#### Namespaces + + The following namespaces are included by default: + +- System + +- System.Collection + +- System.Text + +- System.Text.RegularExpressions + +- System.Xml + +- System.Xml.Xsl + +- System.Xml.XPath + +- Microsoft.VisualBasic (when the script language is VB) + + You can add support for additional namespaces using the `namespace` attribute. The attribute value is the name of the namespace. + +```xml + + + + +``` + +## Example + + The following example uses an embedded script to calculate the circumference of a circle given its radius. + [!code-csharp[XSLT_Script#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XSLT_Script/CS/xslt_script.cs#1)] - [!code-vb[XSLT_Script#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_Script/VB/xslt_script.vb#1)] - -#### number.xml - - [!code-xml[XSLT_Script#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/number.xml#2)] - -#### calc.xsl - - [!code-xml[XSLT_Script#3](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/calc.xsl#3)] - -### Output - -```xml - - - 12 - 75.36 - - - 37.5 - 235.5 - - -``` - + [!code-vb[XSLT_Script#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XSLT_Script/VB/xslt_script.vb#1)] + +#### number.xml + + [!code-xml[XSLT_Script#2](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/number.xml#2)] + +#### calc.xsl + + [!code-xml[XSLT_Script#3](../../../../samples/snippets/xml/VS_Snippets_Data/XSLT_Script/XML/calc.xsl#3)] + +### Output + +```xml + + + 12 + 75.36 + + + 37.5 + 235.5 + + +``` + ## See also - [XSLT Transformations](xslt-transformations.md) diff --git a/docs/standard/generics/index.md b/docs/standard/generics/index.md index 0d55c8d23ded6..d2b9f72c077d4 100644 --- a/docs/standard/generics/index.md +++ b/docs/standard/generics/index.md @@ -124,7 +124,7 @@ The namespace provides generic i Support for generics has been added to the namespace for examining generic types and generic methods, to for emitting dynamic assemblies that contain generic types and methods, and to for generating source graphs that include generics. -The common language runtime provides new opcodes and prefixes to support generic types in Microsoft intermediate language (MSIL), including , , , , and . +The common language runtime provides new opcodes and prefixes to support generic types in common intermediate language (CIL), including , , , , and . Visual C++, C#, and Visual Basic all provide full support for defining and using generics. For more information about language support, see [Generic Types in Visual Basic](../../visual-basic/programming-guide/language-features/data-types/generic-types.md), [Introduction to Generics](../../csharp/fundamentals/types/generics.md), and [Overview of Generics in Visual C++](/cpp/windows/overview-of-generics-in-visual-cpp). diff --git a/docs/standard/managed-code.md b/docs/standard/managed-code.md index 59b1686777cc8..98fdf4e2bd6cd 100644 --- a/docs/standard/managed-code.md +++ b/docs/standard/managed-code.md @@ -18,9 +18,9 @@ Managed code is written in one of the high-level languages that can be run on to What is "Intermediate Language" (or IL for short)? It is a product of compilation of code written in high-level .NET languages. Once you compile your code written in one of these languages, you will get a binary that is made out of IL. It is important to note that the IL is independent from any specific language that runs on top of the runtime; there is even a separate specification for it that you can read if you're so inclined. -Once you produce IL from your high-level code, you will most likely want to run it. This is where the CLR takes over and starts the process of **Just-In-Time** compiling, or **JIT-ing** your code from IL to machine code that can actually be run on a CPU. In this way, the CLR knows exactly what your code is doing and can effectively _manage_ it. +Once you produce IL from your high-level code, you will most likely want to run it. This is where the CLR takes over and starts the process of **Just-In-Time** compiling, or **JIT-ing** your code from IL to machine code that can actually be run on a CPU. In this way, the CLR knows exactly what your code is doing and can effectively *manage* it. -Intermediate Language is sometimes also called Common Intermediate Language (CIL) or Microsoft Intermediate Language (MSIL). +Intermediate Language is sometimes also called Common Intermediate Language (CIL) or common intermediate language (CIL). ## Unmanaged code interoperability diff --git a/docs/standard/managed-execution-process.md b/docs/standard/managed-execution-process.md index 691e0ffbc70cc..635cc914c3291 100644 --- a/docs/standard/managed-execution-process.md +++ b/docs/standard/managed-execution-process.md @@ -11,106 +11,73 @@ helpviewer_keywords: - "common language runtime, managed execution process" ms.assetid: 476b03dc-2b12-49a7-b067-41caeaa2f533 --- -# Managed Execution Process +# Managed execution process - The managed execution process includes the following steps, which are discussed in detail later in this topic: +The managed execution process includes the following steps, which are discussed in detail later in this topic: -1. [Choosing a compiler](#choosing_a_compiler). +1. Choosing a compiler. To obtain the benefits provided by the common language runtime, you must use one or more language compilers that target the runtime. +1. Compiling your code to intermediate language. Compiling translates your source code into common intermediate language (CIL) and generates the required metadata. +1. Compiling CIL to native code. At execution time, a just-in-time (JIT) compiler translates the CIL into native code. During this compilation, code must pass a verification process that examines the CIL and metadata to find out whether the code can be determined to be type safe. +1. Running code. The common language runtime provides the infrastructure that enables execution to take place and services that can be used during execution. - To obtain the benefits provided by the common language runtime, you must use one or more language compilers that target the runtime. - -2. [Compiling your code to MSIL](#compiling_to_msil). - - Compiling translates your source code into Microsoft intermediate language (MSIL) and generates the required metadata. - -3. [Compiling MSIL to native code](#compiling_msil_to_native_code). - - At execution time, a just-in-time (JIT) compiler translates the MSIL into native code. During this compilation, code must pass a verification process that examines the MSIL and metadata to find out whether the code can be determined to be type safe. - -4. [Running code](#running_code). - - The common language runtime provides the infrastructure that enables execution to take place and services that can be used during execution. - - - -## Choosing a Compiler +## Choose a compiler To obtain the benefits provided by the common language runtime (CLR), you must use one or more language compilers that target the runtime, such as Visual Basic, C#, Visual C++, F#, or one of many third-party compilers such as an Eiffel, Perl, or COBOL compiler. Because it is a multilanguage execution environment, the runtime supports a wide variety of data types and language features. The language compiler you use determines which runtime features are available, and you design your code using those features. Your compiler, not the runtime, establishes the syntax your code must use. If your component must be completely usable by components written in other languages, your component's exported types must expose only language features that are included in the Common Language Specification (CLS). You can use the attribute to ensure that your code is CLS-compliant. For more information, see [Language independence and language-independent components](language-independence.md). - [Back to top](#introduction) - - - -## Compiling to MSIL - - When compiling to managed code, the compiler translates your source code into Microsoft intermediate language (MSIL), which is a CPU-independent set of instructions that can be efficiently converted to native code. MSIL includes instructions for loading, storing, initializing, and calling methods on objects, as well as instructions for arithmetic and logical operations, control flow, direct memory access, exception handling, and other operations. Before code can be run, MSIL must be converted to CPU-specific code, usually by a [just-in-time (JIT) compiler](#compiling_msil_to_native_code). Because the common language runtime supplies one or more JIT compilers for each computer architecture it supports, the same set of MSIL can be JIT-compiled and run on any supported architecture. +## Compile to CIL - When a compiler produces MSIL, it also produces metadata. Metadata describes the types in your code, including the definition of each type, the signatures of each type's members, the members that your code references, and other data that the runtime uses at execution time. The MSIL and metadata are contained in a portable executable (PE) file that is based on and that extends the published Microsoft PE and common object file format (COFF) used historically for executable content. This file format, which accommodates MSIL or native code as well as metadata, enables the operating system to recognize common language runtime images. The presence of metadata in the file together with MSIL enables your code to describe itself, which means that there is no need for type libraries or Interface Definition Language (IDL). The runtime locates and extracts the metadata from the file as needed during execution. + When compiling to managed code, the compiler translates your source code into common intermediate language (CIL), which is a CPU-independent set of instructions that can be efficiently converted to native code. CIL includes instructions for loading, storing, initializing, and calling methods on objects, as well as instructions for arithmetic and logical operations, control flow, direct memory access, exception handling, and other operations. Before code can be run, CIL must be converted to CPU-specific code, usually by a [just-in-time (JIT) compiler](#compile-cil-to-native-code). Because the common language runtime supplies one or more JIT compilers for each computer architecture it supports, the same set of CIL can be JIT-compiled and run on any supported architecture. - [Back to top](#introduction) + When a compiler produces CIL, it also produces metadata. Metadata describes the types in your code, including the definition of each type, the signatures of each type's members, the members that your code references, and other data that the runtime uses at execution time. The CIL and metadata are contained in a portable executable (PE) file that is based on and that extends the published Microsoft PE and common object file format (COFF) used historically for executable content. This file format, which accommodates CIL or native code as well as metadata, enables the operating system to recognize common language runtime images. The presence of metadata in the file together with CIL enables your code to describe itself, which means that there is no need for type libraries or Interface Definition Language (IDL). The runtime locates and extracts the metadata from the file as needed during execution. - +## Compile CIL to native code -## Compiling MSIL to Native Code - - Before you can run Microsoft intermediate language (MSIL), it must be compiled against the common language runtime to native code for the target machine architecture. .NET provides two ways to perform this conversion: + Before you can run common intermediate language (CIL), it must be compiled against the common language runtime to native code for the target machine architecture. .NET provides two ways to perform this conversion: - A .NET just-in-time (JIT) compiler. - - [Ngen.exe (Native Image Generator)](../framework/tools/ngen-exe-native-image-generator.md). -### Compilation by the JIT Compiler - - JIT compilation converts MSIL to native code on demand at application run time, when the contents of an assembly are loaded and executed. Because the common language runtime supplies a JIT compiler for each supported CPU architecture, developers can build a set of MSIL assemblies that can be JIT-compiled and run on different computers with different machine architectures. However, if your managed code calls platform-specific native APIs or a platform-specific class library, it will run only on that operating system. +### Compilation by the JIT compiler - JIT compilation takes into account the possibility that some code might never be called during execution. Instead of using time and memory to convert all the MSIL in a PE file to native code, it converts the MSIL as needed during execution and stores the resulting native code in memory so that it is accessible for subsequent calls in the context of that process. The loader creates and attaches a stub to each method in a type when the type is loaded and initialized. When a method is called for the first time, the stub passes control to the JIT compiler, which converts the MSIL for that method into native code and modifies the stub to point directly to the generated native code. Therefore, subsequent calls to the JIT-compiled method go directly to the native code. + JIT compilation converts CIL to native code on demand at application run time, when the contents of an assembly are loaded and executed. Because the common language runtime supplies a JIT compiler for each supported CPU architecture, developers can build a set of CIL assemblies that can be JIT-compiled and run on different computers with different machine architectures. However, if your managed code calls platform-specific native APIs or a platform-specific class library, it will run only on that operating system. -### Install-Time Code Generation Using NGen.exe + JIT compilation takes into account the possibility that some code might never be called during execution. Instead of using time and memory to convert all the CIL in a PE file to native code, it converts the CIL as needed during execution and stores the resulting native code in memory so that it is accessible for subsequent calls in the context of that process. The loader creates and attaches a stub to each method in a type when the type is loaded and initialized. When a method is called for the first time, the stub passes control to the JIT compiler, which converts the CIL for that method into native code and modifies the stub to point directly to the generated native code. Therefore, subsequent calls to the JIT-compiled method go directly to the native code. - Because the JIT compiler converts an assembly's MSIL to native code when individual methods defined in that assembly are called, it affects performance adversely at run time. In most cases, that diminished performance is acceptable. More importantly, the code generated by the JIT compiler is bound to the process that triggered the compilation. It cannot be shared across multiple processes. To allow the generated code to be shared across multiple invocations of an application or across multiple processes that share a set of assemblies, the common language runtime supports an ahead-of-time compilation mode. This ahead-of-time compilation mode uses the [Ngen.exe (Native Image Generator)](../framework/tools/ngen-exe-native-image-generator.md) to convert MSIL assemblies to native code much like the JIT compiler does. However, the operation of Ngen.exe differs from that of the JIT compiler in three ways: +### Install-time code generation using NGen.exe -- It performs the conversion from MSIL to native code before running the application instead of while the application is running. + Because the JIT compiler converts an assembly's CIL to native code when individual methods defined in that assembly are called, it affects performance adversely at run time. In most cases, that diminished performance is acceptable. More importantly, the code generated by the JIT compiler is bound to the process that triggered the compilation. It cannot be shared across multiple processes. To allow the generated code to be shared across multiple invocations of an application or across multiple processes that share a set of assemblies, the common language runtime supports an ahead-of-time compilation mode. This ahead-of-time compilation mode uses the [Ngen.exe (Native Image Generator)](../framework/tools/ngen-exe-native-image-generator.md) to convert CIL assemblies to native code much like the JIT compiler does. However, the operation of Ngen.exe differs from that of the JIT compiler in three ways: +- It performs the conversion from CIL to native code before running the application instead of while the application is running. - It compiles an entire assembly at a time, instead of one method at a time. - - It persists the generated code in the Native Image Cache as a file on disk. -### Code Verification +### Code verification - As part of its compilation to native code, the MSIL code must pass a verification process unless an administrator has established a security policy that allows the code to bypass verification. Verification examines MSIL and metadata to find out whether the code is type safe, which means that it accesses only the memory locations it is authorized to access. Type safety helps isolate objects from each other and helps protect them from inadvertent or malicious corruption. It also provides assurance that security restrictions on code can be reliably enforced. + As part of its compilation to native code, the CIL code must pass a verification process unless an administrator has established a security policy that allows the code to bypass verification. Verification examines CIL and metadata to find out whether the code is type safe, which means that it accesses only the memory locations it is authorized to access. Type safety helps isolate objects from each other and helps protect them from inadvertent or malicious corruption. It also provides assurance that security restrictions on code can be reliably enforced. The runtime relies on the fact that the following statements are true for code that is verifiably type safe: - A reference to a type is strictly compatible with the type being referenced. - - Only appropriately defined operations are invoked on an object. - - Identities are what they claim to be. - During the verification process, MSIL code is examined in an attempt to confirm that the code can access memory locations and call methods only through properly defined types. For example, code cannot allow an object's fields to be accessed in a manner that allows memory locations to be overrun. Additionally, verification inspects code to determine whether the MSIL has been correctly generated, because incorrect MSIL can lead to a violation of the type safety rules. The verification process passes a well-defined set of type-safe code, and it passes only code that is type safe. However, some type-safe code might not pass verification because of some limitations of the verification process, and some languages, by design, do not produce verifiably type-safe code. If type-safe code is required by the security policy but the code does not pass verification, an exception is thrown when the code is run. - - [Back to top](#introduction) - - + During the verification process, CIL code is examined in an attempt to confirm that the code can access memory locations and call methods only through properly defined types. For example, code cannot allow an object's fields to be accessed in a manner that allows memory locations to be overrun. Additionally, verification inspects code to determine whether the CIL has been correctly generated, because incorrect CIL can lead to a violation of the type safety rules. The verification process passes a well-defined set of type-safe code, and it passes only code that is type safe. However, some type-safe code might not pass verification because of some limitations of the verification process, and some languages, by design, do not produce verifiably type-safe code. If type-safe code is required by the security policy but the code does not pass verification, an exception is thrown when the code is run. -## Running Code +## Run code - The common language runtime provides the infrastructure that enables managed execution to take place and services that can be used during execution. Before a method can be run, it must be compiled to processor-specific code. Each method for which MSIL has been generated is JIT-compiled when it is called for the first time, and then run. The next time the method is run, the existing JIT-compiled native code is run. The process of JIT-compiling and then running the code is repeated until execution is complete. + The common language runtime provides the infrastructure that enables managed execution to take place and services that can be used during execution. Before a method can be run, it must be compiled to processor-specific code. Each method for which CIL has been generated is JIT-compiled when it is called for the first time, and then run. The next time the method is run, the existing JIT-compiled native code is run. The process of JIT-compiling and then running the code is repeated until execution is complete. During execution, managed code receives services such as garbage collection, security, interoperability with unmanaged code, cross-language debugging support, and enhanced deployment and versioning support. In Microsoft Windows Vista, the operating system loader checks for managed modules by examining a bit in the COFF header. The bit being set denotes a managed module. If the loader detects managed modules, it loads mscoree.dll, and `_CorValidateImage` and `_CorImageUnloading` notify the loader when the managed module images are loaded and unloaded. `_CorValidateImage` performs the following actions: 1. Ensures that the code is valid managed code. - 2. Changes the entry point in the image to an entry point in the runtime. On 64-bit Windows, `_CorValidateImage` modifies the image that is in memory by transforming it from PE32 to PE32+ format. - [Back to top](#introduction) - ## See also - [Overview](../framework/get-started/overview.md) diff --git a/docs/standard/metadata-and-self-describing-components.md b/docs/standard/metadata-and-self-describing-components.md index 2dbb04453f153..8d3f7c36bf9fc 100644 --- a/docs/standard/metadata-and-self-describing-components.md +++ b/docs/standard/metadata-and-self-describing-components.md @@ -20,7 +20,7 @@ ms.assetid: 3dd13c5d-a508-455b-8dce-0a852882a5a7 In the past, a software component (.exe or .dll) that was written in one language could not easily use a software component that was written in another language. COM provided a step towards solving this problem. .NET makes component interoperation even easier by allowing compilers to emit additional declarative information into all modules and assemblies. This information, called metadata, helps components to interact seamlessly. - Metadata is binary information describing your program that is stored either in a common language runtime portable executable (PE) file or in memory. When you compile your code into a PE file, metadata is inserted into one portion of the file, and your code is converted to Microsoft intermediate language (MSIL) and inserted into another portion of the file. Every type and member that is defined and referenced in a module or assembly is described within metadata. When code is executed, the runtime loads metadata into memory and references it to discover information about your code's classes, members, inheritance, and so on. + Metadata is binary information describing your program that is stored either in a common language runtime portable executable (PE) file or in memory. When you compile your code into a PE file, metadata is inserted into one portion of the file, and your code is converted to common intermediate language (CIL) and inserted into another portion of the file. Every type and member that is defined and referenced in a module or assembly is described within metadata. When code is executed, the runtime loads metadata into memory and references it to discover information about your code's classes, members, inheritance, and so on. Metadata describes every type and member defined in your code in a language-neutral manner. Metadata stores the following information: @@ -62,7 +62,7 @@ Metadata is the key to a simpler programming model, and eliminates the need for ## Metadata and the PE File Structure -Metadata is stored in one section of a .NET portable executable (PE) file, while Microsoft intermediate language (MSIL) is stored in another section of the PE file. The metadata portion of the file contains a series of table and heap data structures. The MSIL portion contains MSIL and metadata tokens that reference the metadata portion of the PE file. You might encounter metadata tokens when you use tools such as the [MSIL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md) to view your code's MSIL, for example. +Metadata is stored in one section of a .NET portable executable (PE) file, while common intermediate language (CIL) is stored in another section of the PE file. The metadata portion of the file contains a series of table and heap data structures. The CIL portion contains CIL and metadata tokens that reference the metadata portion of the PE file. You might encounter metadata tokens when you use tools such as the [IL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md) to view your code's CIL, for example. ### Metadata Tables and Heaps @@ -72,9 +72,9 @@ Metadata also stores information in four heap structures: string, blob, user str ### Metadata Tokens -Each row of each metadata table is uniquely identified in the MSIL portion of the PE file by a metadata token. Metadata tokens are conceptually similar to pointers, persisted in MSIL, that reference a particular metadata table. +Each row of each metadata table is uniquely identified in the CIL portion of the PE file by a metadata token. Metadata tokens are conceptually similar to pointers, persisted in CIL, that reference a particular metadata table. -A metadata token is a four-byte number. The top byte denotes the metadata table to which a particular token refers (method, type, and so on). The remaining three bytes specify the row in the metadata table that corresponds to the programming element being described. If you define a method in C# and compile it into a PE file, the following metadata token might exist in the MSIL portion of the PE file: +A metadata token is a four-byte number. The top byte denotes the metadata table to which a particular token refers (method, type, and so on). The remaining three bytes specify the row in the metadata table that corresponds to the programming element being described. If you define a method in C# and compile it into a PE file, the following metadata token might exist in the CIL portion of the PE file: `0x06000004` @@ -87,7 +87,7 @@ When a program is compiled for the common language runtime, it is converted to a |PE section|Contents of PE section| |----------------|----------------------------| |PE header|The index of the PE file's main sections and the address of the entry point.

The runtime uses this information to identify the file as a PE file and to determine where execution starts when loading the program into memory.| -|MSIL instructions|The Microsoft intermediate language instructions (MSIL) that make up your code. Many MSIL instructions are accompanied by metadata tokens.| +|CIL instructions|The Microsoft intermediate language instructions (CIL) that make up your code. Many CIL instructions are accompanied by metadata tokens.| |Metadata|Metadata tables and heaps. The runtime uses this section to record information about every type and member in your code. This section also includes custom attributes and security information.| ## Run-Time Use of Metadata @@ -126,9 +126,9 @@ public class MyApp } ``` -When the code runs, the runtime loads the module into memory and consults the metadata for this class. Once loaded, the runtime performs extensive analysis of the method's Microsoft intermediate language (MSIL) stream to convert it to fast native machine instructions. The runtime uses a just-in-time (JIT) compiler to convert the MSIL instructions to native machine code one method at a time as needed. +When the code runs, the runtime loads the module into memory and consults the metadata for this class. Once loaded, the runtime performs extensive analysis of the method's common intermediate language (CIL) stream to convert it to fast native machine instructions. The runtime uses a just-in-time (JIT) compiler to convert the CIL instructions to native machine code one method at a time as needed. -The following example shows part of the MSIL produced from the previous code's `Main` function. You can view the MSIL and metadata from any .NET application using the [MSIL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md). +The following example shows part of the CIL produced from the previous code's `Main` function. You can view the CIL and metadata from any .NET application using the [CIL Disassembler (Ildasm.exe)](../framework/tools/ildasm-exe-il-disassembler.md). ```console .entrypoint @@ -147,7 +147,7 @@ IL_000c: ldloc.1 IL_000d: call int32 ConsoleApplication.MyApp::Add(int32,int32) /* 06000003 */ ``` -The JIT compiler reads the MSIL for the whole method, analyzes it thoroughly, and generates efficient native instructions for the method. At `IL_000d`, a metadata token for the `Add` method (`/*` `06000003 */`) is encountered and the runtime uses the token to consult the third row of the **MethodDef** table. +The JIT compiler reads the CIL for the whole method, analyzes it thoroughly, and generates efficient native instructions for the method. At `IL_000d`, a metadata token for the `Add` method (`/*` `06000003 */`) is encountered and the runtime uses the token to consult the third row of the **MethodDef** table. The following table shows part of the **MethodDef** table referenced by the metadata token that describes the `Add` method. While other metadata tables exist in this assembly and have their own unique values, only this table is discussed. @@ -157,8 +157,8 @@ The following table shows part of the **MethodDef** table referenced by the meta |2|0x00002058|IL

Managed|Public

Static

ReuseSlot|Main|String| |3|0x0000208c|IL

Managed|Public

Static

ReuseSlot|Add|int, int, int| -Each column of the table contains important information about your code. The **RVA** column allows the runtime to calculate the starting memory address of the MSIL that defines this method. The **ImplFlags** and **Flags** columns contain bitmasks that describe the method (for example, whether the method is public or private). The **Name** column indexes the name of the method from the string heap. The **Signature** column indexes the definition of the method's signature in the blob heap. +Each column of the table contains important information about your code. The **RVA** column allows the runtime to calculate the starting memory address of the CIL that defines this method. The **ImplFlags** and **Flags** columns contain bitmasks that describe the method (for example, whether the method is public or private). The **Name** column indexes the name of the method from the string heap. The **Signature** column indexes the definition of the method's signature in the blob heap. -The runtime calculates the desired offset address from the **RVA** column in the third row and returns this address to the JIT compiler, which then proceeds to the new address. The JIT compiler continues to process MSIL at the new address until it encounters another metadata token and the process is repeated. +The runtime calculates the desired offset address from the **RVA** column in the third row and returns this address to the JIT compiler, which then proceeds to the new address. The JIT compiler continues to process CIL at the new address until it encounters another metadata token and the process is repeated. Using metadata, the runtime has access to all the information it needs to load your code and process it into native machine instructions. In this manner, metadata enables self-describing files and, together with the common type system, cross-language inheritance. diff --git a/docs/standard/security/key-security-concepts.md b/docs/standard/security/key-security-concepts.md index e8851fb1488b6..bef72483aa4b4 100644 --- a/docs/standard/security/key-security-concepts.md +++ b/docs/standard/security/key-security-concepts.md @@ -2,11 +2,11 @@ description: "Learn more about: Key Security Concepts" title: "Key Security Concepts" ms.date: 07/15/2020 -dev_langs: +dev_langs: - "csharp" - "vb" - "cpp" -helpviewer_keywords: +helpviewer_keywords: - "unauthorized access" - "permissions [.NET]" - "security [.NET], about security" @@ -19,54 +19,54 @@ ms.assetid: 3cfced4f-ea02-4e66-ae98-d69286363e98 > > For information about ASP.NET Core, see [Overview of ASP.NET Core Security](/aspnet/core/security/). -.NET offers role-based security to help address security concerns about mobile code and to provide support that enables components to determine what users are authorized to do. - -## Type safety and security - -Type-safe code accesses only the memory locations it is authorized to access. (For this discussion, type safety specifically refers to memory type safety and should not be confused with type safety in a broader respect.) For example, type-safe code cannot read values from another object's private fields. It accesses types only in well-defined, allowable ways. - -During just-in-time (JIT) compilation, an optional verification process examines the metadata and Microsoft intermediate language (MSIL) of a method to be JIT-compiled into native machine code to verify that they are type safe. This process is skipped if the code has permission to bypass verification. For more information about verification, see [Managed Execution Process](../managed-execution-process.md). - -Although verification of type safety is not mandatory to run managed code, type safety plays a crucial role in assembly isolation and security enforcement. When code is type safe, the common language runtime can completely isolate assemblies from each other. This isolation helps ensure that assemblies cannot adversely affect each other and it increases application reliability. Type-safe components can execute safely in the same process even if they are trusted at different levels. When code is not type safe, unwanted side effects can occur. For example, the runtime cannot prevent managed code from calling into native (unmanaged) code and performing malicious operations. When code is type safe, the runtime's security enforcement mechanism ensures that it does not access native code unless it has permission to do so. All code that is not type safe must have been granted with the passed enum member to run. - -[!INCLUDE [cas-deprecated](../../../includes/cas-deprecated.md)] - -## Principal - -A principal represents the identity and role of a user and acts on the user's behalf. Role-based security in .NET supports three kinds of principals: - -- Generic principals represent users and roles that exist independent of Windows users and roles. - -- Windows principals represent Windows users and their roles (or their Windows groups). A Windows principal can impersonate another user, which means that the principal can access a resource on a user's behalf while presenting the identity that belongs to that user. - -- Custom principals can be defined by an application in any way that is needed for that particular application. They can extend the basic notion of the principal's identity and roles. - -For more information, see [Principal and Identity Objects](principal-and-identity-objects.md). - -## Authentication - -Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. - -A variety of authentication mechanisms are used today, many of which can be used with .NET role-based security. Some of the most commonly used mechanisms are basic, digest, Passport, operating system (such as NTLM or Kerberos), or application-defined mechanisms. - -### Example - -The following example requires that the active principal be an administrator. The `name` parameter is `null`, which allows any user who is an administrator to pass the demand. - +.NET offers role-based security to help address security concerns about mobile code and to provide support that enables components to determine what users are authorized to do. + +## Type safety and security + +Type-safe code accesses only the memory locations it is authorized to access. (For this discussion, type safety specifically refers to memory type safety and should not be confused with type safety in a broader respect.) For example, type-safe code cannot read values from another object's private fields. It accesses types only in well-defined, allowable ways. + +During just-in-time (JIT) compilation, an optional verification process examines the metadata and common intermediate language (CIL) of a method to be JIT-compiled into native machine code to verify that they are type safe. This process is skipped if the code has permission to bypass verification. For more information about verification, see [Managed Execution Process](../managed-execution-process.md). + +Although verification of type safety is not mandatory to run managed code, type safety plays a crucial role in assembly isolation and security enforcement. When code is type safe, the common language runtime can completely isolate assemblies from each other. This isolation helps ensure that assemblies cannot adversely affect each other and it increases application reliability. Type-safe components can execute safely in the same process even if they are trusted at different levels. When code is not type safe, unwanted side effects can occur. For example, the runtime cannot prevent managed code from calling into native (unmanaged) code and performing malicious operations. When code is type safe, the runtime's security enforcement mechanism ensures that it does not access native code unless it has permission to do so. All code that is not type safe must have been granted with the passed enum member to run. + +[!INCLUDE [cas-deprecated](../../../includes/cas-deprecated.md)] + +## Principal + +A principal represents the identity and role of a user and acts on the user's behalf. Role-based security in .NET supports three kinds of principals: + +- Generic principals represent users and roles that exist independent of Windows users and roles. + +- Windows principals represent Windows users and their roles (or their Windows groups). A Windows principal can impersonate another user, which means that the principal can access a resource on a user's behalf while presenting the identity that belongs to that user. + +- Custom principals can be defined by an application in any way that is needed for that particular application. They can extend the basic notion of the principal's identity and roles. + +For more information, see [Principal and Identity Objects](principal-and-identity-objects.md). + +## Authentication + +Authentication is the process of discovering and verifying the identity of a principal by examining the user's credentials and validating those credentials against some authority. The information obtained during authentication is directly usable by your code. You can also use .NET role-based security to authenticate the current user and to determine whether to allow that principal to access your code. See the overloads of the method for examples of how to authenticate the principal for specific roles. For example, you can use the overload to determine if the current user is a member of the Administrators group. + +A variety of authentication mechanisms are used today, many of which can be used with .NET role-based security. Some of the most commonly used mechanisms are basic, digest, Passport, operating system (such as NTLM or Kerberos), or application-defined mechanisms. + +### Example + +The following example requires that the active principal be an administrator. The `name` parameter is `null`, which allows any user who is an administrator to pass the demand. + > [!NOTE] -> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that requires you to be an administrator, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. - +> In Windows Vista, User Account Control (UAC) determines the privileges of a user. If you are a member of the Built-in Administrators group, you are assigned two run-time access tokens: a standard user access token and an administrator access token. By default, you are in the standard user role. To execute the code that requires you to be an administrator, you must first elevate your privileges from standard user to administrator. You can do this when you start an application by right-clicking the application icon and indicating that you want to run as an administrator. + [!code-cpp[Classic PrincipalPermission Example#1](../../../samples/snippets/cpp/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/CPP/source.cpp#1)] [!code-csharp[Classic PrincipalPermission Example#1](../../../samples/snippets/csharp/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/CS/source.cs#1)] - [!code-vb[Classic PrincipalPermission Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/VB/source.vb#1)] - - The following example demonstrates how to determine the identity of the principal and the roles available to the principal. An application of this example might be to confirm that the current user is in a role you allow for using your application. - + [!code-vb[Classic PrincipalPermission Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_Classic/classic PrincipalPermission Example/VB/source.vb#1)] + + The following example demonstrates how to determine the identity of the principal and the roles available to the principal. An application of this example might be to confirm that the current user is in a role you allow for using your application. + [!code-cpp[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/cpp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CPP/source.cpp#1)] [!code-csharp[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/csharp/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/CS/source.cs#1)] - [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#1)] - -## Authorization + [!code-vb[System.Security.Principal.WindowsBuiltInRole Example#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR_System/system.Security.Principal.WindowsBuiltInRole Example/VB/source.vb#1)] + +## Authorization Authorization is the process of determining whether a principal is allowed to perform a requested action. Authorization occurs after authentication and uses information about the principal's identity and roles to determine what resources the principal can access. You can use .NET role-based security to implement authorization. diff --git a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md index 3717d2663bdcd..582e764863191 100644 --- a/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md +++ b/docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md @@ -16,7 +16,7 @@ ms.topic: how-to This article shows how to migrate from [Newtonsoft.Json](https://www.newtonsoft.com/json) to . -The `System.Text.Json` namespace provides functionality for serializing to and deserializing from JavaScript Object Notation (JSON). The `System.Text.Json` library is included in the runtime for [.NET Core 3.1](https://dotnet.microsoft.com/download/dotnet/3.1) and later versions. For other target frameworks, install the [System.Text.Json](https://www.nuget.org/packages/System.Text.Json) NuGet package. The package supports: +The `System.Text.Json` namespace provides functionality for serializing to and deserializing from JavaScript Object Notation (JSON). The `System.Text.Json` library is included in the runtime for .NET Core 3.1 and later versions. For other target frameworks, install the [System.Text.Json](https://www.nuget.org/packages/System.Text.Json) NuGet package. The package supports: * .NET Standard 2.0 and later versions * .NET Framework 4.7.2 and later versions diff --git a/docs/standard/serialization/xml-serializer-generator-tool-sgen-exe.md b/docs/standard/serialization/xml-serializer-generator-tool-sgen-exe.md index f2b980ef2dea7..a63b5e920ce84 100644 --- a/docs/standard/serialization/xml-serializer-generator-tool-sgen-exe.md +++ b/docs/standard/serialization/xml-serializer-generator-tool-sgen-exe.md @@ -1,67 +1,72 @@ --- -title: "XML Serializer Generator Tool (Sgen.exe)" +title: "XML Serializer Generator tool (Sgen.exe)" description: The XML Serializer Generator creates an XML serialization assembly for types in an assembly, which improves the startup performance of XmlSerializer. -ms.date: "03/30/2017" -ms.assetid: cc1d1f1c-fb26-4be9-885a-3fe84c81cec6 +ms.date: 04/23/2024 --- -# XML Serializer Generator Tool (Sgen.exe) +# XML Serializer Generator tool (Sgen.exe) The XML Serializer Generator creates an XML serialization assembly for types in a specified assembly. The serialization assembly improves the startup performance of a when it serializes or deserializes objects of the specified types. - + +> [!NOTE] +> This tool is specific to .NET Framework assemblies. To generator XML serializers for .NET (Core) assemblies, see [Use Microsoft XML Serializer Generator on .NET Core](../../core/additional-tools/xml-serializer-generator.md). + ## Syntax Run the tool from the command line. - -```console -sgen [options] + +```console +sgen [options] ``` - + > [!TIP] > For .NET Framework tools to function properly, you must either use [Visual Studio Developer Command Prompt or Visual Studio Developer PowerShell](/visualstudio/ide/reference/command-prompt-powershell) or set the `Path`, `Include`, and `Lib` environment variables correctly. To set these environment variables, run *SDKVars.bat*, which is located in the *\\\\\Bin* directory. - -## Parameters - -|Option|Description| -|------------|-----------------| -|**/a\[ssembly\]:**_filename_|Generates serialization code for all the types contained in the assembly or executable specified by *filename*. Only one file name can be provided. If this argument is repeated, the last file name is used.| -|**/c\[ompiler\]:**_options_|Specifies the options to pass to the C# compiler. All csc.exe options are supported as they are passed to the compiler. This can be used to specify that the assembly should be signed and to specify the key file.| -|**/d\[ebug\]**|Generates an image that can be used with a debugger.| -|**/f\[orce\]**|Forces the overwriting of an existing assembly of the same name. The default is **false**.| -|**/help or /?**|Displays command syntax and options for the tool.| -|**/k\[eep\]**|Suppresses the deletion of the generated source files and other temporary files after they have been compiled into the serialization assembly. This can be used to determine whether the tool is generating serialization code for a particular type.| -|**/n\[ologo\]**|Suppresses the display of the Microsoft startup banner.| -|**/o\[ut\]:**_path_|Specifies the directory in which to save the generated assembly. **Note:** The name of the generated assembly is composed of the name of the input assembly plus "xmlSerializers.dll".| -|**/p\[roxytypes\]**|Generates serialization code only for the XML Web service proxy types.| -|**/r\[eference\]:**_assemblyfiles_|Specifies the assemblies that are referenced by the types requiring XML serialization. Accepts multiple assembly files separated by commas.| -|**/s\[ilent\]**|Suppresses the display of success messages.| -|**/t\[ype\]:**_type_|Generates serialization code only for the specified type.| -|**/v\[erbose\]**|Displays verbose output for debugging. Lists types from the target assembly that cannot be serialized with the .| -|**/?**|Displays command syntax and options for the tool.| - -## Remarks - - When the XML Serializer Generator is not used, a generates serialization code and a serialization assembly for each type every time an application is run. To improve the performance of XML serialization startup, use the Sgen.exe tool to generate those assemblies in advance. These assemblies can then be deployed with the application. - - The XML Serializer Generator can also improve the performance of clients that use XML Web service proxies to communicate with servers because the serialization process will not incur a performance hit when the type is loaded the first time. - - These generated assemblies cannot be used on the server side of a Web service. This tool is only for Web service clients and manual serialization scenarios. - - If the assembly containing the type to serialize is named MyType.dll, then the associated serialization assembly will be named MyType.XmlSerializers.dll. + +## Parameters + +| Option | Description | +|--------|-------------| +|**/a\[ssembly\]:**_filename_|Generates serialization code for all the types contained in the assembly or executable specified by *filename*. Only one file name can be provided. If this argument is repeated, the last file name is used.| +|**/c\[ompiler\]:**_options_|Specifies the options to pass to the C# compiler. All csc.exe options are supported as they are passed to the compiler. This can be used to specify that the assembly should be signed and to specify the key file.| +|**/d\[ebug\]**|Generates an image that can be used with a debugger.| +|**/f\[orce\]**|Forces the overwriting of an existing assembly of the same name. The default is **false**.| +|**/help** or **/?**|Displays command syntax and options for the tool.| +|**/k\[eep\]**|Suppresses the deletion of the generated source files and other temporary files after they have been compiled into the serialization assembly. This can be used to determine whether the tool is generating serialization code for a particular type.| +|**/n\[ologo\]**|Suppresses the display of the Microsoft startup banner.| +|**/o\[ut\]:**_path_|Specifies the directory in which to save the generated assembly. **Note:** The name of the generated assembly is composed of the name of the input assembly plus "xmlSerializers.dll".| +|**/p\[roxytypes\]**|Generates serialization code only for the XML Web service proxy types.| +|**/r\[eference\]:**_assemblyfiles_|Specifies the assemblies that are referenced by the types requiring XML serialization. Accepts multiple assembly files separated by commas.| +|**/s\[ilent\]**|Suppresses the display of success messages.| +|**/t\[ype\]:**_type_|Generates serialization code only for the specified type.| +|**/v\[erbose\]**|Displays verbose output for debugging. Lists types from the target assembly that cannot be serialized with the .| +|**/?**|Displays command syntax and options for the tool.| + +## Remarks + +When the XML Serializer Generator is not used, generates serialization code and a serialization assembly for each type every time an application is run. To improve the performance of XML serialization startup, use the Sgen.exe tool to generate those assemblies in advance. These assemblies can then be deployed with the application. + +The XML Serializer Generator can also improve the performance of clients that use XML web service proxies to communicate with servers, because the serialization process won't incur a performance hit when the type is loaded the first time. + +The generated assemblies can't be used on the server side of a web service. This tool is only for web service clients and manual serialization scenarios. > [!NOTE] -> The `sgen` tool is not compatible with [init](../../csharp/language-reference/keywords/init.md)-only setters. The tool will fail if the target assembly contains any public properties that use this feature. - -## Examples +> The `sgen` tool is not compatible with [init-only](../../csharp/language-reference/keywords/init.md) setters. The tool will fail if the target assembly contains any public properties that use this feature. + +### Naming + +If the assembly containing the type to serialize is named *MyType.dll*, then the associated serialization assembly will be named *MyType.XmlSerializers.dll*. + +## Examples - The following command creates an assembly named Data.XmlSerializers.dll for serializing all the types contained in the assembly named Data.dll. - -```console +The following command creates an assembly named *Data.XmlSerializers.dll* for serializing all the types contained in the assembly named *Data.dll*. + +```console sgen Data.dll -``` - - The Data.XmlSerializers.dll assembly can be referenced from code that needs to serialize and deserialize the types in Data.dll. - +``` + +The *Data.XmlSerializers.dll* assembly can be referenced from code that needs to serialize and deserialize the types in *Data.dll*. + ## See also +- [Use Microsoft XML Serializer Generator on .NET Core](../../core/additional-tools/xml-serializer-generator.md) - [Tools](../../framework/tools/index.md) - [Developer command-line shells](/visualstudio/ide/reference/command-prompt-powershell) diff --git a/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md b/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md index 0f38c474e65e8..124f891ee5944 100644 --- a/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md +++ b/docs/visual-basic/programming-guide/com-interop/walkthrough-office-programming.md @@ -1,6 +1,6 @@ --- title: "Walkthrough: Office Programming - Visual Basic" -description: Learn about the features Visual Studio offers in Visual Basic that improve Microsoft Office programming. +description: Learn about the features Visual Studio offers in Visual Basic that improve Microsoft Office programming. ms.date: 02/15/2023 ms.topic: tutorial dev_langs: @@ -112,7 +112,7 @@ You must have Microsoft Office Excel and Microsoft Office Word installed on your 2. Select the **Start**. Locate **Microsoft Visual Studio \** and open a developer command prompt. -3. Type `ildasm` in the Developer Command Prompt for Visual Studio window, and then press ENTER. The IL DASM window appears. +3. Type `ildasm` in the Developer Command Prompt for Visual Studio window, and then press Enter. The IL DASM window appears. 4. On the **File** menu in the IL DASM window, select **File** > **Open**. Double-click **Visual Studio \**, and then double-click **Projects**. Open the folder for your project, and look in the bin/Debug folder for *your project name*.dll. Double-click *your project name*.dll. A new window displays your project's attributes, in addition to references to other modules and assemblies. Note that namespaces `Microsoft.Office.Interop.Excel` and `Microsoft.Office.Interop.Word` are included in the assembly. By default in Visual Studio, the compiler imports the types you need from a referenced PIA into your assembly. diff --git a/docs/visual-basic/programming-guide/concepts/expression-trees/index.md b/docs/visual-basic/programming-guide/concepts/expression-trees/index.md index 4f3f2a29b5c48..61f1a1df5ad5f 100644 --- a/docs/visual-basic/programming-guide/concepts/expression-trees/index.md +++ b/docs/visual-basic/programming-guide/concepts/expression-trees/index.md @@ -6,142 +6,142 @@ ms.assetid: 8bbbb02d-7ffc-476b-8c25-118d82bf5d46 --- # Expression Trees (Visual Basic) -Expression trees represent code in a tree-like data structure, where each node is an expression, for example, a method call or a binary operation such as `x < y`. - - You can compile and run code represented by expression trees. This enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to: Use Expression Trees to Build Dynamic Queries (Visual Basic)](how-to-use-expression-trees-to-build-dynamic-queries.md). - - Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and the .NET Framework and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (MSIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). - - You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. - -## Creating Expression Trees from Lambda Expressions - - When a lambda expression is assigned to a variable of type , the compiler emits code to build an expression tree that represents the lambda expression. - - The Visual Basic compiler can generate expression trees only from expression lambdas (or single-line lambdas). It cannot parse statement lambdas (or multi-line lambdas). For more information about lambda expressions in Visual Basic, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). - - The following code examples demonstrate how to have the Visual Basic compiler create an expression tree that represents the lambda expression `Function(num) num < 5`. - -```vb -Dim lambda As Expression(Of Func(Of Integer, Boolean)) = - Function(num) num < 5 -``` - -## Creating Expression Trees by Using the API - - To create expression trees by using the API, use the class. This class contains static factory methods that create expression tree nodes of specific types, for example, , which represents a variable or parameter, or , which represents a method call. , , and the other expression-specific types are also defined in the namespace. These types derive from the abstract type . - - The following code example demonstrates how to create an expression tree that represents the lambda expression `Function(num) num < 5` by using the API. - -```vb -' Import the following namespace to your project: System.Linq.Expressions - -' Manually build the expression tree for the lambda expression num => num < 5. -Dim numParam As ParameterExpression = Expression.Parameter(GetType(Integer), "num") -Dim five As ConstantExpression = Expression.Constant(5, GetType(Integer)) -Dim numLessThanFive As BinaryExpression = Expression.LessThan(numParam, five) -Dim lambda1 As Expression(Of Func(Of Integer, Boolean)) = - Expression.Lambda(Of Func(Of Integer, Boolean))( - numLessThanFive, - New ParameterExpression() {numParam}) -``` - - In .NET Framework 4 or later, the expression trees API also supports assignments and control flow expressions such as loops, conditional blocks, and `try-catch` blocks. By using the API, you can create expression trees that are more complex than those that can be created from lambda expressions by the Visual Basic compiler. The following example demonstrates how to create an expression tree that calculates the factorial of a number. - -```vb -' Creating a parameter expression. -Dim value As ParameterExpression = - Expression.Parameter(GetType(Integer), "value") - +Expression trees represent code in a tree-like data structure, where each node is an expression, for example, a method call or a binary operation such as `x < y`. + + You can compile and run code represented by expression trees. This enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to: Use Expression Trees to Build Dynamic Queries (Visual Basic)](how-to-use-expression-trees-to-build-dynamic-queries.md). + + Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and the .NET Framework and to enable compiler writers to emit expression trees instead of common intermediate language (CIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). + + You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. + +## Creating Expression Trees from Lambda Expressions + + When a lambda expression is assigned to a variable of type , the compiler emits code to build an expression tree that represents the lambda expression. + + The Visual Basic compiler can generate expression trees only from expression lambdas (or single-line lambdas). It cannot parse statement lambdas (or multi-line lambdas). For more information about lambda expressions in Visual Basic, see [Lambda Expressions](../../language-features/procedures/lambda-expressions.md). + + The following code examples demonstrate how to have the Visual Basic compiler create an expression tree that represents the lambda expression `Function(num) num < 5`. + +```vb +Dim lambda As Expression(Of Func(Of Integer, Boolean)) = + Function(num) num < 5 +``` + +## Creating Expression Trees by Using the API + + To create expression trees by using the API, use the class. This class contains static factory methods that create expression tree nodes of specific types, for example, , which represents a variable or parameter, or , which represents a method call. , , and the other expression-specific types are also defined in the namespace. These types derive from the abstract type . + + The following code example demonstrates how to create an expression tree that represents the lambda expression `Function(num) num < 5` by using the API. + +```vb +' Import the following namespace to your project: System.Linq.Expressions + +' Manually build the expression tree for the lambda expression num => num < 5. +Dim numParam As ParameterExpression = Expression.Parameter(GetType(Integer), "num") +Dim five As ConstantExpression = Expression.Constant(5, GetType(Integer)) +Dim numLessThanFive As BinaryExpression = Expression.LessThan(numParam, five) +Dim lambda1 As Expression(Of Func(Of Integer, Boolean)) = + Expression.Lambda(Of Func(Of Integer, Boolean))( + numLessThanFive, + New ParameterExpression() {numParam}) +``` + + In .NET Framework 4 or later, the expression trees API also supports assignments and control flow expressions such as loops, conditional blocks, and `try-catch` blocks. By using the API, you can create expression trees that are more complex than those that can be created from lambda expressions by the Visual Basic compiler. The following example demonstrates how to create an expression tree that calculates the factorial of a number. + +```vb +' Creating a parameter expression. +Dim value As ParameterExpression = + Expression.Parameter(GetType(Integer), "value") + ' Creating an expression to hold a local variable. -Dim result As ParameterExpression = - Expression.Parameter(GetType(Integer), "result") - -' Creating a label to jump to from a loop. -Dim label As LabelTarget = Expression.Label(GetType(Integer)) - -' Creating a method body. -Dim block As BlockExpression = Expression.Block( - New ParameterExpression() {result}, - Expression.Assign(result, Expression.Constant(1)), - Expression.Loop( - Expression.IfThenElse( - Expression.GreaterThan(value, Expression.Constant(1)), - Expression.MultiplyAssign(result, - Expression.PostDecrementAssign(value)), - Expression.Break(label, result) - ), - label - ) -) - -' Compile an expression tree and return a delegate. -Dim factorial As Integer = - Expression.Lambda(Of Func(Of Integer, Integer))(block, value).Compile()(5) - -Console.WriteLine(factorial) -' Prints 120. +Dim result As ParameterExpression = + Expression.Parameter(GetType(Integer), "result") + +' Creating a label to jump to from a loop. +Dim label As LabelTarget = Expression.Label(GetType(Integer)) + +' Creating a method body. +Dim block As BlockExpression = Expression.Block( + New ParameterExpression() {result}, + Expression.Assign(result, Expression.Constant(1)), + Expression.Loop( + Expression.IfThenElse( + Expression.GreaterThan(value, Expression.Constant(1)), + Expression.MultiplyAssign(result, + Expression.PostDecrementAssign(value)), + Expression.Break(label, result) + ), + label + ) +) + +' Compile an expression tree and return a delegate. +Dim factorial As Integer = + Expression.Lambda(Of Func(Of Integer, Integer))(block, value).Compile()(5) + +Console.WriteLine(factorial) +' Prints 120. ``` For more information, see [Generating Dynamic Methods with Expression Trees in Visual Studio 2010](https://devblogs.microsoft.com/csharpfaq/generating-dynamic-methods-with-expression-trees-in-visual-studio-2010/), which also applies to later versions of Visual Studio. - -## Parsing Expression Trees - - The following code example demonstrates how the expression tree that represents the lambda expression `Function(num) num < 5` can be decomposed into its parts. - -```vb -' Import the following namespace to your project: System.Linq.Expressions - -' Create an expression tree. -Dim exprTree As Expression(Of Func(Of Integer, Boolean)) = Function(num) num < 5 - -' Decompose the expression tree. -Dim param As ParameterExpression = exprTree.Parameters(0) -Dim operation As BinaryExpression = exprTree.Body -Dim left As ParameterExpression = operation.Left -Dim right As ConstantExpression = operation.Right - -Console.WriteLine(String.Format("Decomposed expression: {0} => {1} {2} {3}", - param.Name, left.Name, operation.NodeType, right.Value)) - -' This code produces the following output: -' -' Decomposed expression: num => num LessThan 5 -``` - -## Immutability of Expression Trees - - Expression trees should be immutable. This means that if you want to modify an expression tree, you must construct a new expression tree by copying the existing one and replacing nodes in it. You can use an expression tree visitor to traverse the existing expression tree. For more information, see [How to: Modify Expression Trees (Visual Basic)](how-to-modify-expression-trees.md). - -## Compiling Expression Trees - - The type provides the method that compiles the code represented by an expression tree into an executable delegate. - - The following code example demonstrates how to compile an expression tree and run the resulting code. - -```vb -' Creating an expression tree. -Dim expr As Expression(Of Func(Of Integer, Boolean)) = - Function(num) num < 5 - -' Compiling the expression tree into a delegate. -Dim result As Func(Of Integer, Boolean) = expr.Compile() - -' Invoking the delegate and writing the result to the console. -Console.WriteLine(result(4)) - -' Prints True. - -' You can also use simplified syntax -' to compile and run an expression tree. -' The following line can replace two previous statements. -Console.WriteLine(expr.Compile()(4)) - -' Also prints True. -``` - - For more information, see [How to: Execute Expression Trees (Visual Basic)](how-to-execute-expression-trees.md). - + +## Parsing Expression Trees + + The following code example demonstrates how the expression tree that represents the lambda expression `Function(num) num < 5` can be decomposed into its parts. + +```vb +' Import the following namespace to your project: System.Linq.Expressions + +' Create an expression tree. +Dim exprTree As Expression(Of Func(Of Integer, Boolean)) = Function(num) num < 5 + +' Decompose the expression tree. +Dim param As ParameterExpression = exprTree.Parameters(0) +Dim operation As BinaryExpression = exprTree.Body +Dim left As ParameterExpression = operation.Left +Dim right As ConstantExpression = operation.Right + +Console.WriteLine(String.Format("Decomposed expression: {0} => {1} {2} {3}", + param.Name, left.Name, operation.NodeType, right.Value)) + +' This code produces the following output: +' +' Decomposed expression: num => num LessThan 5 +``` + +## Immutability of Expression Trees + + Expression trees should be immutable. This means that if you want to modify an expression tree, you must construct a new expression tree by copying the existing one and replacing nodes in it. You can use an expression tree visitor to traverse the existing expression tree. For more information, see [How to: Modify Expression Trees (Visual Basic)](how-to-modify-expression-trees.md). + +## Compiling Expression Trees + + The type provides the method that compiles the code represented by an expression tree into an executable delegate. + + The following code example demonstrates how to compile an expression tree and run the resulting code. + +```vb +' Creating an expression tree. +Dim expr As Expression(Of Func(Of Integer, Boolean)) = + Function(num) num < 5 + +' Compiling the expression tree into a delegate. +Dim result As Func(Of Integer, Boolean) = expr.Compile() + +' Invoking the delegate and writing the result to the console. +Console.WriteLine(result(4)) + +' Prints True. + +' You can also use simplified syntax +' to compile and run an expression tree. +' The following line can replace two previous statements. +Console.WriteLine(expr.Compile()(4)) + +' Also prints True. +``` + + For more information, see [How to: Execute Expression Trees (Visual Basic)](how-to-execute-expression-trees.md). + ## See also - diff --git a/docs/visual-basic/programming-guide/concepts/iterators.md b/docs/visual-basic/programming-guide/concepts/iterators.md index 2a39e1981a200..7df1b2887452c 100644 --- a/docs/visual-basic/programming-guide/concepts/iterators.md +++ b/docs/visual-basic/programming-guide/concepts/iterators.md @@ -410,7 +410,7 @@ In Visual Basic, "Yield" is not a reserved word and has special meaning only whe Although you write an iterator as a method, the compiler translates it into a nested class that is, in effect, a state machine. This class keeps track of the position of the iterator as long the `For Each...Next` loop in the client code continues. -To see what the compiler does, you can use the Ildasm.exe tool to view the Microsoft intermediate language code that is generated for an iterator method. +To see what the compiler does, you can use the Ildasm.exe tool to view the common intermediate language code that is generated for an iterator method. When you create an iterator for a [class](../../language-reference/statements/class-statement.md) or [struct](../../language-reference/statements/structure-statement.md), you do not have to implement the whole interface. When the compiler detects the iterator, it automatically generates the `Current`, `MoveNext`, and `Dispose` methods of the or interface. diff --git a/docs/visual-basic/reference/command-line-compiler/keycontainer.md b/docs/visual-basic/reference/command-line-compiler/keycontainer.md index fa7e540955229..97c8fb8a4f14b 100644 --- a/docs/visual-basic/reference/command-line-compiler/keycontainer.md +++ b/docs/visual-basic/reference/command-line-compiler/keycontainer.md @@ -2,7 +2,7 @@ description: "Learn more about: -keycontainer" title: "-keycontainer" ms.date: 03/10/2018 -helpviewer_keywords: +helpviewer_keywords: - "-keycontainer compiler option [Visual Basic]" - "keycontainer compiler option [Visual Basic]" - "/keycontainer compiler option [Visual Basic]" @@ -10,43 +10,43 @@ ms.assetid: 6a9bc861-1752-4db1-9f64-b5252f0482cc --- # -keycontainer -Specifies a key container name for a key pair to give an assembly a strong name. - -## Syntax - -```console --keycontainer:container -``` - -## Arguments - -|Term|Definition| -|---|---| -|`container`|Required. Container file that contains the key. Enclose the file name in quotation marks ("") if the name contains a space.| - -## Remarks - - The compiler creates the sharable component by inserting a public key into the assembly manifest and by signing the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. The `-i` option installs the key pair into a container. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). - - If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). - - You can also specify this option as a custom attribute () in the source code for any Microsoft intermediate language (MSIL) module. - - You can also pass your encryption information to the compiler with [-keyfile](keyfile.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. - - See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. - +Specifies a key container name for a key pair to give an assembly a strong name. + +## Syntax + +```console +-keycontainer:container +``` + +## Arguments + +|Term|Definition| +|---|---| +|`container`|Required. Container file that contains the key. Enclose the file name in quotation marks ("") if the name contains a space.| + +## Remarks + + The compiler creates the sharable component by inserting a public key into the assembly manifest and by signing the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. The `-i` option installs the key pair into a container. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). + + If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). + + You can also specify this option as a custom attribute () in the source code for any common intermediate language (CIL) module. + + You can also pass your encryption information to the compiler with [-keyfile](keyfile.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. + + See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. + > [!NOTE] -> The `-keycontainer` option is not available from within the Visual Studio development environment; it is available only when compiling from the command line. - -## Example - - The following code compiles source file `Input.vb` and specifies a key container. - -```console -vbc -keycontainer:key1 input.vb -``` - +> The `-keycontainer` option is not available from within the Visual Studio development environment; it is available only when compiling from the command line. + +## Example + + The following code compiles source file `Input.vb` and specifies a key container. + +```console +vbc -keycontainer:key1 input.vb +``` + ## See also - [Assemblies in .NET](../../../standard/assembly/index.md) diff --git a/docs/visual-basic/reference/command-line-compiler/keyfile.md b/docs/visual-basic/reference/command-line-compiler/keyfile.md index c79d77232e553..eb2fa73e94ee2 100644 --- a/docs/visual-basic/reference/command-line-compiler/keyfile.md +++ b/docs/visual-basic/reference/command-line-compiler/keyfile.md @@ -10,35 +10,35 @@ ms.assetid: ffa82a4b-517a-4c6c-9889-5bae7b534bb8 --- # -keyfile -Specifies a file containing a key or key pair to give an assembly a strong name. - -## Syntax - +Specifies a file containing a key or key pair to give an assembly a strong name. + +## Syntax + ```console --keyfile:file -``` - -## Arguments - - `file` - Required. File that contains the key. If the file name contains a space, enclose the name in quotation marks (" "). - -## Remarks - - The compiler inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). - - If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). - - You can also pass your encryption information to the compiler with [-keycontainer](keycontainer.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. - - You can also specify this option as a custom attribute () in the source code for any Microsoft intermediate language module. - - In case both `-keyfile` and [-keycontainer](keycontainer.md) are specified (either by command-line option or by custom attribute) in the same compilation, the compiler first tries the key container. If that succeeds, then the assembly is signed with the information in the key container. If the compiler does not find the key container, it tries the file specified with `-keyfile`. If this succeeds, the assembly is signed with the information in the key file, and the key information is installed in the key container (similar to `sn -i`) so that on the next compilation, the key container will be valid. - - Note that a key file might contain only the public key. - - See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. - +-keyfile:file +``` + +## Arguments + + `file` + Required. File that contains the key. If the file name contains a space, enclose the name in quotation marks (" "). + +## Remarks + + The compiler inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type `sn -k file` at the command line. For more information, see [Sn.exe (Strong Name Tool)](../../../framework/tools/sn-exe-strong-name-tool.md)). + + If you compile with `-target:module`, the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly with [-addmodule](addmodule.md). + + You can also pass your encryption information to the compiler with [-keycontainer](keycontainer.md). Use [-delaysign](delaysign.md) if you want a partially signed assembly. + + You can also specify this option as a custom attribute () in the source code for any common intermediate language module. + + In case both `-keyfile` and [-keycontainer](keycontainer.md) are specified (either by command-line option or by custom attribute) in the same compilation, the compiler first tries the key container. If that succeeds, then the assembly is signed with the information in the key container. If the compiler does not find the key container, it tries the file specified with `-keyfile`. If this succeeds, the assembly is signed with the information in the key file, and the key information is installed in the key container (similar to `sn -i`) so that on the next compilation, the key container will be valid. + + Note that a key file might contain only the public key. + + See [Creating and Using Strong-Named Assemblies](../../../standard/assembly/create-use-strong-named.md) for more information on signing an assembly. + > [!NOTE] > The `-keyfile` option is not available from within the Visual Studio development environment; it is available only when compiling from the command line. diff --git a/docs/visual-basic/reference/command-line-compiler/rootnamespace.md b/docs/visual-basic/reference/command-line-compiler/rootnamespace.md index 1fcf15cb24b32..11b72c43004ac 100644 --- a/docs/visual-basic/reference/command-line-compiler/rootnamespace.md +++ b/docs/visual-basic/reference/command-line-compiler/rootnamespace.md @@ -2,10 +2,10 @@ description: "Learn more about: -rootnamespace" title: "-rootnamespace" ms.date: 03/13/2018 -f1_keywords: +f1_keywords: - "/rootnamespace" - "rootnamespace" -helpviewer_keywords: +helpviewer_keywords: - "/rootnamespace compiler option [Visual Basic]" - "-rootnamespace compiler option [Visual Basic]" - "rootnamespace compiler option [Visual Basic]" @@ -13,38 +13,38 @@ ms.assetid: e9245edf-6bef-420d-a7c7-324117752783 --- # -rootnamespace -Specifies a namespace for all type declarations. - -## Syntax - -```console --rootnamespace:namespace -``` - -## Arguments - -|Term|Definition| -|---|---| -|`namespace`|The name of the namespace in which to enclose all type declarations for the current project.| - -## Remarks - - If you use the Visual Studio executable file (Devenv.exe) to compile a project created in the Visual Studio integrated development environment, use `-rootnamespace` to specify the value of the property. See [Devenv Command Line Switches](/visualstudio/ide/reference/devenv-command-line-switches) for more information. - - Use the common language runtime MSIL Disassembler (`Ildasm.exe`) to view the namespace names in your output file. - -|To set -rootnamespace in the Visual Studio integrated development environment| -|---| -|1. Have a project selected in **Solution Explorer**. On the **Project** menu, click **Properties**.
2. Click the **Application** tab.
3. Modify the value in the **Root Namespace** box.| - -## Example - - The following code compiles `In.vb` and encloses all type declarations in the namespace `mynamespace`. - +Specifies a namespace for all type declarations. + +## Syntax + ```console -vbc -rootnamespace:mynamespace in.vb -``` - +-rootnamespace:namespace +``` + +## Arguments + +|Term|Definition| +|---|---| +|`namespace`|The name of the namespace in which to enclose all type declarations for the current project.| + +## Remarks + + If you use the Visual Studio executable file (Devenv.exe) to compile a project created in the Visual Studio integrated development environment, use `-rootnamespace` to specify the value of the property. See [Devenv Command Line Switches](/visualstudio/ide/reference/devenv-command-line-switches) for more information. + + Use the IL Disassembler tool (`Ildasm.exe`) to view the namespace names in your output file. + +|To set -rootnamespace in the Visual Studio integrated development environment| +|---| +|1. Have a project selected in **Solution Explorer**. On the **Project** menu, click **Properties**.
2. Click the **Application** tab.
3. Modify the value in the **Root Namespace** box.| + +## Example + + The following code compiles `In.vb` and encloses all type declarations in the namespace `mynamespace`. + +```console +vbc -rootnamespace:mynamespace in.vb +``` + ## See also - [Visual Basic Command-Line Compiler](index.md) diff --git a/samples/snippets/core/testing/unit-testing-best-practices/csharp/after/unit-testing-best-practices-after.csproj b/samples/snippets/core/testing/unit-testing-best-practices/csharp/after/unit-testing-best-practices-after.csproj index 4d6cab2389e17..72ae7282b2f08 100644 --- a/samples/snippets/core/testing/unit-testing-best-practices/csharp/after/unit-testing-best-practices-after.csproj +++ b/samples/snippets/core/testing/unit-testing-best-practices/csharp/after/unit-testing-best-practices-after.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/samples/snippets/core/testing/unit-testing-best-practices/csharp/before/unit-testing-best-practices-before.csproj b/samples/snippets/core/testing/unit-testing-best-practices/csharp/before/unit-testing-best-practices-before.csproj index 4d6cab2389e17..72ae7282b2f08 100644 --- a/samples/snippets/core/testing/unit-testing-best-practices/csharp/before/unit-testing-best-practices-before.csproj +++ b/samples/snippets/core/testing/unit-testing-best-practices/csharp/before/unit-testing-best-practices-before.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/samples/snippets/core/testing/unit-testing-using-dotnet-test/csharp/PrimeService.Tests/PrimeService.Tests.csproj b/samples/snippets/core/testing/unit-testing-using-dotnet-test/csharp/PrimeService.Tests/PrimeService.Tests.csproj index 2dd44c5566bd0..a6130c4bdc1ff 100644 --- a/samples/snippets/core/testing/unit-testing-using-dotnet-test/csharp/PrimeService.Tests/PrimeService.Tests.csproj +++ b/samples/snippets/core/testing/unit-testing-using-dotnet-test/csharp/PrimeService.Tests/PrimeService.Tests.csproj @@ -8,8 +8,8 @@ - - + + diff --git a/samples/snippets/core/tutorials/testing-with-cli/csharp/test/NewTypesTests/NewTypesTests.csproj b/samples/snippets/core/tutorials/testing-with-cli/csharp/test/NewTypesTests/NewTypesTests.csproj index 47fcb48359954..6aa5e0194aa46 100644 --- a/samples/snippets/core/tutorials/testing-with-cli/csharp/test/NewTypesTests/NewTypesTests.csproj +++ b/samples/snippets/core/tutorials/testing-with-cli/csharp/test/NewTypesTests/NewTypesTests.csproj @@ -7,8 +7,8 @@ - - + + diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs b/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs deleted file mode 100644 index d18474078efd6..0000000000000 --- a/samples/snippets/csharp/VS_Snippets_VBCSharp/CsLINQGettingStarted/CS/Class1.cs +++ /dev/null @@ -1,254 +0,0 @@ -using System; -using System.Linq; -using System.Collections.Generic; -using System.Text; -using System.Xml.Linq; - -namespace LINQGettingStarted_1; - -class Program //for the Walkthrough topic -{ - // - public class Student - { - public string First { get; set; } - public string Last { get; set; } - public int ID { get; set; } - public List Scores; - } - - // Create a data source by using a collection initializer. - static List students = - [ - new Student {First="Svetlana", Last="Omelchenko", ID=111, Scores= new List {97, 92, 81, 60}}, - new Student {First="Claire", Last="O'Donnell", ID=112, Scores= new List {75, 84, 91, 39}}, - new Student {First="Sven", Last="Mortensen", ID=113, Scores= new List {88, 94, 65, 91}}, - new Student {First="Cesar", Last="Garcia", ID=114, Scores= new List {97, 89, 85, 82}}, - new Student {First="Debra", Last="Garcia", ID=115, Scores= new List {35, 72, 91, 70}}, - new Student {First="Fadi", Last="Fakhouri", ID=116, Scores= new List {99, 86, 90, 94}}, - new Student {First="Hanying", Last="Feng", ID=117, Scores= new List {93, 92, 80, 87}}, - new Student {First="Hugo", Last="Garcia", ID=118, Scores= new List {92, 90, 83, 78}}, - new Student {First="Lance", Last="Tucker", ID=119, Scores= new List {68, 79, 88, 92}}, - new Student {First="Terry", Last="Adams", ID=120, Scores= new List {99, 82, 81, 79}}, - new Student {First="Eugene", Last="Zabokritski", ID=121, Scores= new List {96, 85, 91, 60}}, - new Student {First="Michael", Last="Tucker", ID=122, Scores= new List {94, 92, 91, 91}} - ]; - // - - static void Main() - { - // - // Create the query. - // The first line could also be written as "var studentQuery =" - IEnumerable studentQuery = - from student in students - where student.Scores[0] > 90 - select student; - // - - Console.WriteLine("\nExecuting Query 1............."); - // - // Execute the query. - // var could be used here also. - foreach (Student student in studentQuery) - { - Console.WriteLine("{0}, {1}", student.Last, student.First); - } - - // Output: - // Omelchenko, Svetlana - // Garcia, Cesar - // Fakhouri, Fadi - // Feng, Hanying - // Garcia, Hugo - // Adams, Terry - // Zabokritski, Eugene - // Tucker, Michael - // - - // - IEnumerable> studentQuery2 = - from student in students - group student by student.Last[0]; - // - - Console.WriteLine("\nExecuting Query 2.............."); - // - foreach (IGrouping studentGroup in studentQuery2) - { - Console.WriteLine(studentGroup.Key); - foreach (Student student in studentGroup) - { - Console.WriteLine(" {0}, {1}", - student.Last, student.First); - } - } - - // Output: - // O - // Omelchenko, Svetlana - // O'Donnell, Claire - // M - // Mortensen, Sven - // G - // Garcia, Cesar - // Garcia, Debra - // Garcia, Hugo - // F - // Fakhouri, Fadi - // Feng, Hanying - // T - // Tucker, Lance - // Tucker, Michael - // A - // Adams, Terry - // Z - // Zabokritski, Eugene - // - - Console.WriteLine("\nExecuting Query 3.............."); - // - var studentQuery3 = - from student in students - group student by student.Last[0]; - - foreach (var groupOfStudents in studentQuery3) - { - Console.WriteLine(groupOfStudents.Key); - foreach (var student in groupOfStudents) - { - Console.WriteLine(" {0}, {1}", - student.Last, student.First); - } - } - - // Output: - // O - // Omelchenko, Svetlana - // O'Donnell, Claire - // M - // Mortensen, Sven - // G - // Garcia, Cesar - // Garcia, Debra - // Garcia, Hugo - // F - // Fakhouri, Fadi - // Feng, Hanying - // T - // Tucker, Lance - // Tucker, Michael - // A - // Adams, Terry - // Z - // Zabokritski, Eugene - // - - Console.WriteLine("\nExecuting Query 4.............."); - // - var studentQuery4 = - from student in students - group student by student.Last[0] into studentGroup - orderby studentGroup.Key - select studentGroup; - - foreach (var groupOfStudents in studentQuery4) - { - Console.WriteLine(groupOfStudents.Key); - foreach (var student in groupOfStudents) - { - Console.WriteLine(" {0}, {1}", - student.Last, student.First); - } - } - - // Output: - //A - // Adams, Terry - //F - // Fakhouri, Fadi - // Feng, Hanying - //G - // Garcia, Cesar - // Garcia, Debra - // Garcia, Hugo - //M - // Mortensen, Sven - //O - // Omelchenko, Svetlana - // O'Donnell, Claire - //T - // Tucker, Lance - // Tucker, Michael - //Z - // Zabokritski, Eugene - // - - Console.WriteLine("\nExecuting Query 5.............."); - // - // studentQuery5 is an IEnumerable - // This query returns those students whose - // first test score was higher than their - // average score. - var studentQuery5 = - from student in students - let totalScore = student.Scores[0] + student.Scores[1] + - student.Scores[2] + student.Scores[3] - where totalScore / 4 < student.Scores[0] - select student.Last + " " + student.First; - - foreach (string s in studentQuery5) - { - Console.WriteLine(s); - } - - // Output: - // Omelchenko Svetlana - // O'Donnell Claire - // Mortensen Sven - // Garcia Cesar - // Fakhouri Fadi - // Feng Hanying - // Garcia Hugo - // Adams Terry - // Zabokritski Eugene - // Tucker Michael - // - - Console.WriteLine("\nExecuting Query 6.............."); - - // - var studentQuery6 = - from student in students - let totalScore = student.Scores[0] + student.Scores[1] + - student.Scores[2] + student.Scores[3] - select totalScore; - - double averageScore = studentQuery6.Average(); - Console.WriteLine("Class average score = {0}", averageScore); - - // Output: - // Class average score = 334.166666666667 - // - - Console.WriteLine("\nExecuting Query 7.............."); - // - IEnumerable studentQuery7 = - from student in students - where student.Last == "Garcia" - select student.First; - - Console.WriteLine("The Garcias in the class are:"); - foreach (string s in studentQuery7) - { - Console.WriteLine(s); - } - - // Output: - // The Garcias in the class are: - // Cesar - // Debra - // Hugo - // - } -} diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.cs b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.cs index 84f72e819792e..20f6f0797ce1d 100644 --- a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.cs +++ b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.cs @@ -177,8 +177,6 @@ Drawing a rectangle //-------------------------------------------------------------------------------------- // -using System; - namespace DotNetEvents { // Define a class to hold custom event info @@ -196,7 +194,7 @@ public CustomEventArgs(string message) class Publisher { // Declare the event using EventHandler - public event EventHandler RaiseCustomEvent; + public event EventHandler? RaiseCustomEvent; public void DoSomething() { @@ -213,7 +211,7 @@ protected virtual void OnRaiseCustomEvent(CustomEventArgs e) // Make a temporary copy of the event to avoid possibility of // a race condition if the last subscriber unsubscribes // immediately after the null check and before the event is raised. - EventHandler raiseEvent = RaiseCustomEvent; + EventHandler? raiseEvent = RaiseCustomEvent; // Event will be null if there are no subscribers if (raiseEvent != null) @@ -241,7 +239,7 @@ public Subscriber(string id, Publisher pub) } // Define what actions to take when the event is raised. - void HandleCustomEvent(object sender, CustomEventArgs e) + void HandleCustomEvent(object? sender, CustomEventArgs e) { Console.WriteLine($"{_id} received this message: {e.Message}"); } diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.csproj b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.csproj new file mode 100644 index 0000000000000..8fc28546a07a7 --- /dev/null +++ b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Events.csproj @@ -0,0 +1,12 @@ + + + + Exe + net8.0-windows + enable + enable + true + Events.Program + + + diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Program.cs b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Program.cs new file mode 100644 index 0000000000000..0fd06ec4ae7eb --- /dev/null +++ b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideEvents/CS/Program.cs @@ -0,0 +1,11 @@ +using System; + +namespace Events +{ + class Program + { + static void Main(string[] args) + { + } + } +} diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/ExceptionsTest.cs b/samples/snippets/csharp/concepts/linq/LinqSamples.Test/ExceptionsTest.cs deleted file mode 100644 index 0a4e810acf56f..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/ExceptionsTest.cs +++ /dev/null @@ -1,20 +0,0 @@ -using Xunit; -using static LinqSamples.Test.Shared; - -namespace LinqSamples.Test; - -public class ExceptionsTest -{ - [Fact] - public void Exceptions2Test() - { - StringWriter sw = InitTest(); - - Exceptions.Exceptions2(); - Assert.Equal( -@"Processing C:\newFolder\fileA.txt -Processing C:\newFolder\fileB.txt -Operation is not valid due to the current state of the object. -", sw.ToString()); - } -} diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/LinqSamples.Test.csproj b/samples/snippets/csharp/concepts/linq/LinqSamples.Test/LinqSamples.Test.csproj deleted file mode 100644 index 492bc098c5e09..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/LinqSamples.Test.csproj +++ /dev/null @@ -1,27 +0,0 @@ - - - - net8.0 - enable - enable - false - - - - - - - runtime; build; native; contentfiles; analyzers; buildtransitive - all - - - runtime; build; native; contentfiles; analyzers; buildtransitive - all - - - - - - - - diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/RuntimeFilteringTest.cs b/samples/snippets/csharp/concepts/linq/LinqSamples.Test/RuntimeFilteringTest.cs deleted file mode 100644 index a2ff0d965bcf9..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/RuntimeFilteringTest.cs +++ /dev/null @@ -1,48 +0,0 @@ -using Xunit; -using static LinqSamples.Test.Shared; - -namespace LinqSamples.Test; - -public class RuntimeFilteringTest -{ - [Fact] - public void RuntimeFiltering1Test() - { - StringWriter sw = InitTest(); - - RuntimeFiltering.RuntimeFiltering1(); - Assert.Equal( -@"Garcia: 114 -O'Donnell: 112 -Omelchenko: 111 -Adams: 120 -Feng: 117 -Garcia: 115 -Tucker: 122 -", sw.ToString()); - } - - [Fact] - public void RuntimeFiltering2Test() - { - StringWriter sw = InitTest(); - - RuntimeFiltering.RuntimeFiltering2(); - Assert.Equal( -@"The following students are at an odd year level: -Fakhouri: 116 -Feng: 117 -Garcia: 115 -Mortensen: 113 -Tucker: 119 -Tucker: 122 -The following students are at an even year level: -Adams: 120 -Garcia: 114 -Garcia: 118 -O'Donnell: 112 -Omelchenko: 111 -Zabokritski: 121 -", sw.ToString()); - } -} diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/Shared.cs b/samples/snippets/csharp/concepts/linq/LinqSamples.Test/Shared.cs deleted file mode 100644 index 2b30bb781f50f..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples.Test/Shared.cs +++ /dev/null @@ -1,16 +0,0 @@ -using Xunit; - -// Tests need to be carried out synchronously, otherwise the console output for different tests gets intermingled -[assembly: CollectionBehavior(CollectionBehavior.CollectionPerAssembly)] - -namespace LinqSamples.Test; -public static class Shared -{ - public static StringWriter InitTest() - { - // We want to capture the console output for each test separately - StringWriter sw = new(); - Console.SetOut(sw); - return sw; - } -} diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples.sln b/samples/snippets/csharp/concepts/linq/LinqSamples.sln deleted file mode 100644 index 58cd799622512..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples.sln +++ /dev/null @@ -1,33 +0,0 @@ - -Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio Version 17 -VisualStudioVersion = 17.0.32112.339 -MinimumVisualStudioVersion = 10.0.40219.1 -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "LinqSamples", "LinqSamples\LinqSamples.csproj", "{71FC22FF-3753-4E52-88B0-F1FAE589C4E6}" -EndProject -Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "LinqSamples.Test", "LinqSamples.Test\LinqSamples.Test.csproj", "{A327D876-CCFA-4026-BBA7-79A0ADF81D24}" -EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{1BE239B9-E3A7-4EBB-9A1C-C4774CFED72E}" -EndProject -Global - GlobalSection(SolutionConfigurationPlatforms) = preSolution - Debug|Any CPU = Debug|Any CPU - Release|Any CPU = Release|Any CPU - EndGlobalSection - GlobalSection(ProjectConfigurationPlatforms) = postSolution - {71FC22FF-3753-4E52-88B0-F1FAE589C4E6}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {71FC22FF-3753-4E52-88B0-F1FAE589C4E6}.Debug|Any CPU.Build.0 = Debug|Any CPU - {71FC22FF-3753-4E52-88B0-F1FAE589C4E6}.Release|Any CPU.ActiveCfg = Release|Any CPU - {71FC22FF-3753-4E52-88B0-F1FAE589C4E6}.Release|Any CPU.Build.0 = Release|Any CPU - {A327D876-CCFA-4026-BBA7-79A0ADF81D24}.Debug|Any CPU.ActiveCfg = Debug|Any CPU - {A327D876-CCFA-4026-BBA7-79A0ADF81D24}.Debug|Any CPU.Build.0 = Debug|Any CPU - {A327D876-CCFA-4026-BBA7-79A0ADF81D24}.Release|Any CPU.ActiveCfg = Release|Any CPU - {A327D876-CCFA-4026-BBA7-79A0ADF81D24}.Release|Any CPU.Build.0 = Release|Any CPU - EndGlobalSection - GlobalSection(SolutionProperties) = preSolution - HideSolutionNode = FALSE - EndGlobalSection - GlobalSection(ExtensibilityGlobals) = postSolution - SolutionGuid = {52CFA1E0-ED27-4A13-9749-F5286FD13B89} - EndGlobalSection -EndGlobal diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/GlobalSuppressions.cs b/samples/snippets/csharp/concepts/linq/LinqSamples/GlobalSuppressions.cs deleted file mode 100644 index 873be521ceb8d..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/GlobalSuppressions.cs +++ /dev/null @@ -1,13 +0,0 @@ -// This file is used by Code Analysis to maintain SuppressMessage -// attributes that are applied to this project. -// Project-level suppressions either have no target or are given -// a specific target and scoped to a namespace, type, member, etc. - -using System.Diagnostics.CodeAnalysis; - -[assembly: SuppressMessage("Style", "IDE1006:Naming Styles")] -[assembly: SuppressMessage("Style", "IDE0059:Unnecessary assignment of a value")] -[assembly: SuppressMessage("Style", "IDE0008:Use explicit type")] -[assembly: SuppressMessage("Style", "IDE0062:Make local function 'static'")] -[assembly: SuppressMessage("Style", "IDE0037:Use inferred member name")] -[assembly: SuppressMessage("Performance", "CA1825:Avoid zero-length array allocations")] diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/Program.cs b/samples/snippets/csharp/concepts/linq/LinqSamples/Program.cs deleted file mode 100644 index 9ac780f194e40..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/Program.cs +++ /dev/null @@ -1,15 +0,0 @@ -using LinqSamples; - -QueryCollectionOfObjects.QueryCollectionOfObjects1(); - -ReturnQueryFromMethod.ReturnQueryFromMethod1(); - -StoreResultsOfQueryInMemory.StoreResultsOfQueryInMemory1(); - -RuntimeFiltering.RuntimeFiltering1(); -RuntimeFiltering.RuntimeFiltering2(); - -NullValues.NullValues1(); - -Exceptions.Exceptions1(); -Exceptions.Exceptions2(); diff --git a/samples/snippets/csharp/concepts/linq/LinqSamples/QueryCollectionOfObjects.cs b/samples/snippets/csharp/concepts/linq/LinqSamples/QueryCollectionOfObjects.cs deleted file mode 100644 index c0df4b9bf2ade..0000000000000 --- a/samples/snippets/csharp/concepts/linq/LinqSamples/QueryCollectionOfObjects.cs +++ /dev/null @@ -1,30 +0,0 @@ -using static LinqSamples.Student; - -namespace LinqSamples; - -public static class QueryCollectionOfObjects -{ - public static void QueryCollectionOfObjects1() - { - // - void QueryHighScores(int exam, int score) - { - var highScores = - from student in students - where student.ExamScores[exam] > score - select new - { - Name = student.FirstName, - Score = student.ExamScores[exam] - }; - - foreach (var item in highScores) - { - Console.WriteLine($"{item.Name,-15}{item.Score}"); - } - } - - QueryHighScores(0, 90); - // - } -} diff --git a/samples/snippets/csharp/concepts/linq/how-to-handle-null-values-in-query-expressions_2.cs b/samples/snippets/csharp/concepts/linq/how-to-handle-null-values-in-query-expressions_2.cs deleted file mode 100644 index be0d1762bf986..0000000000000 --- a/samples/snippets/csharp/concepts/linq/how-to-handle-null-values-in-query-expressions_2.cs +++ /dev/null @@ -1,8 +0,0 @@ - void TestMethod(Northwind db) - { - var query = - from o in db.Orders - join e in db.Employees - on o.EmployeeID equals (int?)e.EmployeeID - select new { o.OrderID, e.FirstName }; - } \ No newline at end of file diff --git a/samples/snippets/csharp/programming-guide/classes-and-structs/object-collection-initializers/HowToClassTypedInitializer.cs b/samples/snippets/csharp/programming-guide/classes-and-structs/object-collection-initializers/HowToClassTypedInitializer.cs new file mode 100644 index 0000000000000..0e5a839910fda --- /dev/null +++ b/samples/snippets/csharp/programming-guide/classes-and-structs/object-collection-initializers/HowToClassTypedInitializer.cs @@ -0,0 +1,83 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text; + +namespace object_collection_initializers +{ + // + public class HowToClassTypedInitializer + { + public class EmbeddedClassTypeA + { + public int I { get; set; } + public bool B { get; set; } + public string S { get; set; } + public EmbeddedClassTypeB ClassB { get; set; } + + public override string ToString() => $"{I}|{B}|{S}|||{ClassB}"; + + public EmbeddedClassTypeA() + { + Console.WriteLine($"Entering EmbeddedClassTypeA constructor. Values are: {this}"); + I = 3; + B = true; + S = "abc"; + ClassB = new() { BB = true, BI = 43 }; + Console.WriteLine($"Exiting EmbeddedClassTypeA constructor. Values are: {this})"); + } + } + + public class EmbeddedClassTypeB + { + public int BI { get; set; } + public bool BB { get; set; } + public string BS { get; set; } + + public override string ToString() => $"{BI}|{BB}|{BS}"; + + public EmbeddedClassTypeB() + { + Console.WriteLine($"Entering EmbeddedClassTypeB constructor. Values are: {this}"); + BI = 23; + BB = false; + BS = "BBBabc"; + Console.WriteLine($"Exiting EmbeddedClassTypeB constructor. Values are: {this})"); + } + } + + public static void Main() + { + var a = new EmbeddedClassTypeA + { + I = 103, + B = false, + ClassB = { BI = 100003 } + }; + Console.WriteLine($"After initializing EmbeddedClassTypeA: {a}"); + + var a2 = new EmbeddedClassTypeA + { + I = 103, + B = false, + ClassB = new() { BI = 100003 } //New instance + }; + Console.WriteLine($"After initializing EmbeddedClassTypeA a2: {a2}"); + } + + // Output: + //Entering EmbeddedClassTypeA constructor Values are: 0|False|||| + //Entering EmbeddedClassTypeB constructor Values are: 0|False| + //Exiting EmbeddedClassTypeB constructor Values are: 23|False|BBBabc) + //Exiting EmbeddedClassTypeA constructor Values are: 3|True|abc|||43|True|BBBabc) + //After initializing EmbeddedClassTypeA: 103|False|abc|||100003|True|BBBabc + //Entering EmbeddedClassTypeA constructor Values are: 0|False|||| + //Entering EmbeddedClassTypeB constructor Values are: 0|False| + //Exiting EmbeddedClassTypeB constructor Values are: 23|False|BBBabc) + //Exiting EmbeddedClassTypeA constructor Values are: 3|True|abc|||43|True|BBBabc) + //Entering EmbeddedClassTypeB constructor Values are: 0|False| + //Exiting EmbeddedClassTypeB constructor Values are: 23|False|BBBabc) + //After initializing EmbeddedClassTypeA a2: 103|False|abc|||100003|False|BBBabc + } + // +} diff --git a/samples/snippets/csharp/xunit-test/xunit-test.csproj b/samples/snippets/csharp/xunit-test/xunit-test.csproj index 90055c05a868d..3871f9c80aa57 100644 --- a/samples/snippets/csharp/xunit-test/xunit-test.csproj +++ b/samples/snippets/csharp/xunit-test/xunit-test.csproj @@ -7,8 +7,8 @@ - - + + diff --git a/samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.vbproj b/samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.vbproj index 29e64205aaf37..0b409b601bd1b 100644 --- a/samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.vbproj +++ b/samples/snippets/visualbasic/programming-guide/dynamic-linq-expression-trees/dynamic-linq-expression-trees.vbproj @@ -9,7 +9,7 @@ - +