diff --git a/.github/workflows/check-for-build-warnings.yml b/.github/workflows/check-for-build-warnings.yml index 8de6e8d71e647..329951ad4cc4c 100644 --- a/.github/workflows/check-for-build-warnings.yml +++ b/.github/workflows/check-for-build-warnings.yml @@ -16,7 +16,7 @@ jobs: pull-requests: write steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-orphaned-articles.yml b/.github/workflows/cleanrepo-orphaned-articles.yml index 8c348f340ef5f..9cbbafb279a83 100644 --- a/.github/workflows/cleanrepo-orphaned-articles.yml +++ b/.github/workflows/cleanrepo-orphaned-articles.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-orphaned-images.yml b/.github/workflows/cleanrepo-orphaned-images.yml index c183cd5da8e84..a8c5d743d0892 100644 --- a/.github/workflows/cleanrepo-orphaned-images.yml +++ b/.github/workflows/cleanrepo-orphaned-images.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-orphaned-includes.yml b/.github/workflows/cleanrepo-orphaned-includes.yml index f7aaf0de88347..69af8390cd4e4 100644 --- a/.github/workflows/cleanrepo-orphaned-includes.yml +++ b/.github/workflows/cleanrepo-orphaned-includes.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-orphaned-snippets.yml b/.github/workflows/cleanrepo-orphaned-snippets.yml index 037c9ed693ce7..7a4bb337bd0bf 100644 --- a/.github/workflows/cleanrepo-orphaned-snippets.yml +++ b/.github/workflows/cleanrepo-orphaned-snippets.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-redirect-hops.yml b/.github/workflows/cleanrepo-redirect-hops.yml index 7b5d456d19725..c35b85ff79fbc 100644 --- a/.github/workflows/cleanrepo-redirect-hops.yml +++ b/.github/workflows/cleanrepo-redirect-hops.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-relative-links.yml b/.github/workflows/cleanrepo-relative-links.yml index 8a5c30dc821be..8edc0f4777218 100644 --- a/.github/workflows/cleanrepo-relative-links.yml +++ b/.github/workflows/cleanrepo-relative-links.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/cleanrepo-replace-redirects.yml b/.github/workflows/cleanrepo-replace-redirects.yml index 34cef4a14d119..71bb722c52fdf 100644 --- a/.github/workflows/cleanrepo-replace-redirects.yml +++ b/.github/workflows/cleanrepo-replace-redirects.yml @@ -17,7 +17,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/dependabot-bot.yml b/.github/workflows/dependabot-bot.yml index bbe2989d27f21..c5af1a3c21cea 100644 --- a/.github/workflows/dependabot-bot.yml +++ b/.github/workflows/dependabot-bot.yml @@ -26,7 +26,7 @@ jobs: # Checkout the repo into the workspace within the VM steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml index 222623af3d2a5..def9e325879a0 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/dependency-review.yml @@ -17,7 +17,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/do-not-merge-label-check.yml b/.github/workflows/do-not-merge-label-check.yml index 8c55958a9e78b..8e7bfbf798573 100644 --- a/.github/workflows/do-not-merge-label-check.yml +++ b/.github/workflows/do-not-merge-label-check.yml @@ -22,7 +22,7 @@ jobs: - 'DO NOT MERGE' steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/docs-verifier.yml b/.github/workflows/docs-verifier.yml index b326b60ebe051..17099df95dcc2 100644 --- a/.github/workflows/docs-verifier.yml +++ b/.github/workflows/docs-verifier.yml @@ -14,7 +14,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/live-protection.yml b/.github/workflows/live-protection.yml index 9eb0c0fbb9c97..761caff2441ef 100644 --- a/.github/workflows/live-protection.yml +++ b/.github/workflows/live-protection.yml @@ -11,7 +11,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml index da0ca5d1b61fd..d0fb274ed50b6 100644 --- a/.github/workflows/markdownlint.yml +++ b/.github/workflows/markdownlint.yml @@ -22,7 +22,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/profanity-filter.yml b/.github/workflows/profanity-filter.yml index 4bb8eddabab2e..2ba6a6f7abf09 100644 --- a/.github/workflows/profanity-filter.yml +++ b/.github/workflows/profanity-filter.yml @@ -19,7 +19,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/quest-bulk.yml b/.github/workflows/quest-bulk.yml index fc5b09fcc21be..0323ef7d6e3b3 100644 --- a/.github/workflows/quest-bulk.yml +++ b/.github/workflows/quest-bulk.yml @@ -28,7 +28,7 @@ jobs: if: ${{ github.repository_owner == 'dotnet' }} steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/quest.yml b/.github/workflows/quest.yml index 842316eae22cb..1f2e887ffa714 100644 --- a/.github/workflows/quest.yml +++ b/.github/workflows/quest.yml @@ -29,7 +29,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/scorecards.yml b/.github/workflows/scorecards.yml index 19dbcf93e178c..d82db1a2a82bc 100644 --- a/.github/workflows/scorecards.yml +++ b/.github/workflows/scorecards.yml @@ -31,7 +31,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit @@ -71,6 +71,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: "Upload to code-scanning" - uses: github/codeql-action/upload-sarif@6bc82e05fd0ea64601dd4b465378bbcf57de0314 # v3.29.5 + uses: github/codeql-action/upload-sarif@45cbd0c69e560cd9e7cd7f8c32362050c9b7ded2 # v3.29.5 with: sarif_file: results.sarif diff --git a/.github/workflows/snippets5000.yml b/.github/workflows/snippets5000.yml index 79f7a32212678..61c1b75ceb779 100644 --- a/.github/workflows/snippets5000.yml +++ b/.github/workflows/snippets5000.yml @@ -14,7 +14,7 @@ on: default: 'Manual run' env: - DOTNET_VERSION: '10.0.*' + DOTNET_VERSION: '11.0.*' DOTNET_QUALITY: 'preview' DOTNET_DO_INSTALL: 'true' # To install a version of .NET not provided by the runner, set to true EnableNuGetPackageRestore: 'True' @@ -31,7 +31,7 @@ jobs: steps: # Checkout the repository for the PR - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index ae280d83e4aa9..1fba899049282 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -16,7 +16,7 @@ jobs: steps: - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.github/workflows/version-sweep.yml b/.github/workflows/version-sweep.yml index 2b18017fb3c78..4fca2a60d238f 100644 --- a/.github/workflows/version-sweep.yml +++ b/.github/workflows/version-sweep.yml @@ -34,7 +34,7 @@ jobs: # Start the .NET version updater action # A composite of the .NET Version Sweeper and the .NET Upgrade Assistant - name: Harden Runner - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9 # v2.14.1 + uses: step-security/harden-runner@5ef0c079ce82195b2a36a210272d6b661572d83e # v2.14.2 with: egress-policy: audit diff --git a/.openpublishing.redirection.csharp.json b/.openpublishing.redirection.csharp.json index 4706854645830..0092422dc85fe 100644 --- a/.openpublishing.redirection.csharp.json +++ b/.openpublishing.redirection.csharp.json @@ -5014,7 +5014,7 @@ }, { "source_path_from_root": "/docs/csharp/whats-new.md", - "redirect_url": "/dotnet/csharp/whats-new/csharp-14", + "redirect_url": "/dotnet/csharp/whats-new/csharp-15", "redirect_document_id": true }, { @@ -5055,7 +5055,7 @@ }, { "source_path_from_root": "/docs/csharp/whats-new/index.md", - "redirect_url": "/dotnet/csharp/whats-new/csharp-14", + "redirect_url": "/dotnet/csharp/whats-new/csharp-15", "ms.custom": "updateeachrelease" }, { diff --git a/.openpublishing.redirection.framework.json b/.openpublishing.redirection.framework.json index 0325364c7de54..355f0803a6195 100644 --- a/.openpublishing.redirection.framework.json +++ b/.openpublishing.redirection.framework.json @@ -2023,6 +2023,11 @@ "redirect_url": "/dotnet/framework/release-notes/2024/04-09-april-security-and-quality-rollup", "redirect_document_id": true }, + { + "source_path_from_root": "/docs/framework/release-notes/2026/01-29-october-cumulative-update-preview.md", + "redirect_url": "/dotnet/framework/release-notes/2026/01-29-january-cumulative-update-preview", + "redirect_document_id": true + }, { "source_path_from_root": "/docs/framework/resources/creating-resource-files-for-desktop-apps.md", "redirect_url": "/dotnet/core/extensions/create-resource-files", diff --git a/docfx.json b/docfx.json index 32baf4eabedc3..30fbfafc3f690 100644 --- a/docfx.json +++ b/docfx.json @@ -74,6 +74,7 @@ "Compiler Breaking Changes - DotNet 8.md", "Compiler Breaking Changes - DotNet 9.md", "Compiler Breaking Changes - DotNet 10.md", + "Compiler Breaking Changes - DotNet 11.md", "Deviations from Standard.md" ], "src": "_roslyn/docs/compilers/CSharp", @@ -513,11 +514,12 @@ "_csharplang/proposals/csharp-12.0/*.md": "08/15/2023", "_csharplang/proposals/csharp-13.0/*.md": "10/31/2024", "_csharplang/proposals/csharp-14.0/*.md": "08/06/2025", - "_csharplang/proposals/*.md": "08/06/2025", + "_csharplang/proposals/*.md": "02/04/2025", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "11/08/2022", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "11/08/2023", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "11/09/2024", - "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 10.md": "01/09/2024", + "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 10.md": "11/09/2024", + "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 11.md": "01/09/2025", "_roslyn/docs/compilers/CSharp/Deviations from Standard.md": "04/24/2025", "_vblang/spec/*.md": "07/21/2017" }, @@ -693,10 +695,12 @@ "_csharplang/proposals/csharp-14.0/ignored-directives.md": "Ignored preprocessor directives", "_csharplang/proposals/csharp-14.0/extension-operators.md": "Extension operators", "_csharplang/proposals/csharp-14.0/optional-and-named-parameters-in-expression-trees.md": "Optional and named parameters in expression trees", + "_csharplang/proposals/collection-expression-arguments.md": "Collection expression arguments", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "C# compiler breaking changes since C# 10", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "C# compiler breaking changes since C# 11", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "C# compiler breaking changes since C# 12", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 10.md": "C# compiler breaking changes since C# 13", + "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 11.md": "C# compiler breaking changes since C# 14", "_roslyn/docs/compilers/CSharp/Deviations from Standard.md": "Deviations from the C# standard", "_vblang/spec/introduction.md": "Introduction", "_vblang/spec/lexical-grammar.md": "Lexical grammar", @@ -819,10 +823,12 @@ "_csharplang/proposals/csharp-14.0/ignored-directives.md": "This proposal allows a source file to include ignored directives. In most cases, ignored directives are used for file-based apps, for example `#!`", "_csharplang/proposals/csharp-14.0/extension-operators.md": "This proposal extends the proposal for extensions to include *extension operators*, where an operator can be an extension member.", "_csharplang/proposals/csharp-14.0/optional-and-named-parameters-in-expression-trees.md": "This proposal allows an expression tree to include named and optional parameters. This enables expression trees to be more flexible in how they are constructed.", + "_csharplang/proposals/collection-expression-arguments.md": "This proposal introduces collection expression arguments.", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 7.md": "Learn about any breaking changes since the initial release of C# 10 and included in C# 11", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 8.md": "Learn about any breaking changes since the initial release of C# 11 and included in C# 12", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 9.md": "Learn about any breaking changes since the initial release of C# 12 and included in C# 13", "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 10.md": "Learn about any breaking changes since the initial release of C# 13 and included in C# 14", + "_roslyn/docs/compilers/CSharp/Compiler Breaking Changes - DotNet 11.md": "Learn about any breaking changes since the initial release of C# 14 and included in C# 15", "_roslyn/docs/compilers/CSharp/Deviations from Standard.md": "Learn about any deviations from the C# standard", "_vblang/spec/introduction.md": "This chapter provides an overview of the Visual Basic language and its design goals.", "_vblang/spec/lexical-grammar.md": "This chapter defines the lexical grammar for Visual Basic.", diff --git a/docs/ai/azure-ai-services-authentication.md b/docs/ai/azure-ai-services-authentication.md index bbb0e6debda8c..1d457b9de9cd1 100644 --- a/docs/ai/azure-ai-services-authentication.md +++ b/docs/ai/azure-ai-services-authentication.md @@ -1,6 +1,6 @@ --- title: Authenticate to Azure OpenAI using .NET -description: Learn about the different options to authenticate to Azure OpenAI and other services using .NET +description: Learn about the different options to authenticate to Azure OpenAI and other services using .NET. author: alexwolfmsft ms.topic: concept-article ms.date: 04/09/2025 @@ -8,7 +8,7 @@ ms.date: 04/09/2025 # Azure AI services authentication and authorization using .NET -Application requests to Azure AI Services must be authenticated. In this article, you explore the options available to authenticate to Azure OpenAI and other AI services using .NET. These concepts apply to the Semantic Kernel SDK, as well as SDKs from specific services such as Azure OpenAI. Most AI services offer two primary ways to authenticate apps and users: +Application requests to Azure AI Services must be authenticated. In this article, you explore the options available to authenticate to Azure OpenAI and other AI services using .NET. Most AI services offer two primary ways to authenticate apps and users: - **Key-based authentication** provides access to an Azure service using secret key values. These secret values are sometimes known as API keys or access keys depending on the service. - **Microsoft Entra ID** provides a comprehensive identity and access management solution to ensure that the correct identities have the correct level of access to different Azure resources. @@ -80,18 +80,18 @@ az login ### Configure the app code -Use the [`Azure.Identity`](/dotnet/api/overview/azure/identity-readme) client library from the Azure SDK to implement Microsoft Entra authentication in your code. The `Azure.Identity` libraries include the `DefaultAzureCredential` class, which automatically discovers available Azure credentials based on the current environment and tooling available. Visit the [Azure SDK for .NET](/dotnet/api/azure.identity.defaultazurecredential) documentation for the full set of supported environment credentials and the order in which they are searched. +Use the [`Azure.Identity`](/dotnet/api/overview/azure/identity-readme) client library from the Azure SDK to implement Microsoft Entra authentication in your code. The `Azure.Identity` libraries include the `DefaultAzureCredential` class, which automatically discovers available Azure credentials based on the current environment and tooling available. For the full set of supported environment credentials and the order in which they are searched, see the [Azure SDK for .NET](/dotnet/api/azure.identity.defaultazurecredential) documentation. -For example, configure Semantic Kernel to authenticate using `DefaultAzureCredential` using the following code: +For example, configure Azure OpenAI to authenticate using `DefaultAzureCredential` using the following code: ```csharp -Kernel kernel = Kernel - .CreateBuilder() - .AddAzureOpenAITextGeneration( - "your-model", - "your-endpoint", - new DefaultAzureCredential()) - .Build(); +AzureOpenAIClient azureClient = + new( + new Uri(endpoint), + new DefaultAzureCredential(new DefaultAzureCredentialOptions() + { TenantId = tenantId } + ) + ); ``` `DefaultAzureCredential` enables apps to be promoted from local development to production without code changes. For example, during development `DefaultAzureCredential` uses your local user credentials from Visual Studio or the Azure CLI to authenticate to the AI service. When the app is deployed to Azure, `DefaultAzureCredential` uses the managed identity that is assigned to your app. diff --git a/docs/ai/conceptual/embeddings.md b/docs/ai/conceptual/embeddings.md index e6ae4047f247c..79ca9ffd307f5 100644 --- a/docs/ai/conceptual/embeddings.md +++ b/docs/ai/conceptual/embeddings.md @@ -49,14 +49,14 @@ You generate embeddings for your raw data by using an AI embedding model, which ### Store and process embeddings in a vector database -After you generate embeddings, you'll need a way to store them so you can later retrieve them with calls to an LLM. Vector databases are designed to store and process vectors, so they're a natural home for embeddings. Different vector databases offer different processing capabilities, so you should choose one based on your raw data and your goals. For information about your options, see [available vector database solutions](vector-databases.md#semantic-kernel-vector-database-solutions). +After you generate embeddings, you'll need a way to store them so you can later retrieve them with calls to an LLM. Vector databases are designed to store and process vectors, so they're a natural home for embeddings. Different vector databases offer different processing capabilities, so you should choose one based on your raw data and your goals. For information about your options, see [Vector databases for .NET + AI](vector-databases.md). ### Using embeddings in your LLM solution -When building LLM-based applications, you can use Semantic Kernel to integrate embedding models and vector stores, so you can quickly pull in text data, and generate and store embeddings. This lets you use a vector database solution to store and retrieve semantic memories. +When building LLM-based applications, you can use Agent Framework to integrate embedding models and vector stores, so you can quickly pull in text data, and generate and store embeddings. This lets you use a vector database solution to store and retrieve semantic memories. ## Related content - [How GenAI and LLMs work](how-genai-and-llms-work.md) - [Retrieval-augmented generation](rag.md) -- [Training: Develop AI agents with Azure OpenAI and Semantic Kernel](/training/paths/develop-ai-agents-azure-open-ai-semantic-kernel-sdk/) +- [Training: Develop an AI agent with Microsoft Agent Framework](/training/modules/develop-ai-agent-with-semantic-kernel/) diff --git a/docs/ai/conceptual/prompt-engineering-dotnet.md b/docs/ai/conceptual/prompt-engineering-dotnet.md index f9f0ac09f0213..d56e361853572 100644 --- a/docs/ai/conceptual/prompt-engineering-dotnet.md +++ b/docs/ai/conceptual/prompt-engineering-dotnet.md @@ -1,11 +1,8 @@ --- -title: Prompt Engineering concepts -description: Learn basic prompt engineering concepts and how to implement them using .NET tools such as the Semantic Kernel SDK -ms.topic: concept-article #Don't change. -ms.date: 04/09/2025 - -#customer intent: As a .NET developer, I want to understand prompt engineering techniques for .NET so that I can build more efficient and targeted AI apps. - +title: Prompt engineering concepts +description: Learn basic prompt engineering concepts and how to implement them using .NET tools such as Microsoft Agent Framework. +ms.topic: concept-article +ms.date: 02/05/2026 --- # Prompt engineering in .NET @@ -14,163 +11,51 @@ In this article, you explore essential prompt engineering concepts. Many AI mode ## Work with prompts -Consider this text generation example where *prompt* is the user input and *completion* is the model output: - -Prompt: **"The president who served the shortest term was "** - -Completion: _"Pedro Lascurain."_ - -The completion appears correct, but what if your app is supposed to help U.S. history students? Pedro Lascurain's 45-minute term is the shortest term for any president, but he served as the president of Mexico. The U.S. history students are probably looking for *"William Henry Harrison"*. Clearly, the app could be more helpful to its intended users if you gave it some context. - -Prompt engineering adds context to the prompt by providing [*instructions*](#use-instructions-to-improve-the-completion), [*examples*](#use-examples-to-guide-the-model), and [*cues*](#understand-cues) to help the model produce better completions. - -Models that support text generation often don't require any specific format, but you should organize your prompts so it's clear what's an instruction and what's an example. Models that support chat-based apps use three roles to organize completions: a system role that controls the chat, a user role to represent user input, and an assistant role for responding to users. Divide your prompts into messages for each role: +Models that support chat-based apps use three roles to organize completions: a *system* role that controls the chat, a *user* role to represent user input, and an *assistant* role for responding to users. Divide your prompts into messages for each role: - [*System messages*](/azure/ai-services/openai/concepts/advanced-prompt-engineering?pivots=programming-language-chat-completions#system-message) give the model instructions about the assistant. A prompt can have only one system message, and it must be the first message. -- *User messages* include prompts from the user and show examples, historical prompts, or contain instructions for the assistant. An example chat completion must have at least one user message. -- *Assistant messages* show example or historical completions, and must contain a response to the preceding user message. Assistant messages aren't required, but if you include one it must be paired with a user message to form an example. +- *User messages* include prompts from the user, examples, or instructions for the assistant. An example chat completion must have at least one user message. +- *Assistant messages* show example or historical completions and must contain a response to the preceding user message. Assistant messages aren't required, but if you include one, it must be paired with a user message to form an example. ## Use instructions to improve the completion -An instruction is text that tells the model how to respond. An instruction can be a directive or an imperative: +An *instruction* is text that tells the model how to respond. An instruction can be a *directive* or an *imperative*: -- *Directives* tell the model how to behave, but aren't simple commands—think character setup for an improv actor: **"You're helping students learn about U.S. history, so talk about the U.S. unless they specifically ask about other countries."** +- *Directives* tell the model how to behave but aren't simple commands—think character setup for an improv actor: **"You're helping students learn about U.S. history, so talk about the U.S. unless they specifically ask about other countries or regions."** - *Imperatives* are unambiguous commands for the model to follow. **"Translate to Tagalog:"** -Directives are more open-ended and flexible than imperatives: - -- You can combine several directives in one instruction. -- Instructions usually work better when you use them with examples. However, because imperatives are unambiguous commands, models don't need examples to understand them (though you might use an example to show the model how to format responses). Because a directive doesn't tell the model exactly what to do, each example can help the model work better. -- It's usually better to break down a difficult instruction into a series of steps, which you can do with a sequence of directives. You should also tell the model to output the result of each step, so that you can easily make granular adjustments. Although you can break down the instruction into steps yourself, it's easier to just tell the model to do it, and to output the result of each step. This approach is called [chain of thought prompting](chain-of-thought-prompting.md). - -### Primary and supporting content add context - -You can provide content to add more context to instructions. - -*Primary content* is text that you want the model to process with an instruction. Whatever action the instruction entails, the model will perform it on the primary content to produce a completion. - -*Supporting content* is text that you refer to in an instruction, but which isn't the target of the instruction. The model uses the supporting content to complete the instruction, which means that supporting content also appears in completions, typically as some kind of structure (such as in headings or column labels). - -Use labels with your instructional content to help the model figure out how to use it with the instruction. Don't worry too much about precision—labels don't have to match instructions exactly because the model will handle things like word form and capitalization. - -Suppose you use the instruction **"Summarize US Presidential accomplishments"** to produce a list. The model might organize and order it in any number of ways. But what if you want the list to group the accomplishments by a specific set of categories? Use supporting content to add that information to the instruction. - -Adjust your instruction so the model groups by category, and append supporting content that specifies those categories: - -```csharp -prompt = """ -Instructions: Summarize US Presidential accomplishments, grouped by category. -Categories: Domestic Policy, US Economy, Foreign Affairs, Space Exploration. -Accomplishments: 'George Washington -- First president of the United States. -- First president to have been a military veteran. -- First president to be elected to a second term in office. -- Received votes from every presidential elector in an election. -- Filled the entire body of the United States federal judges; including the Supreme Court. -- First president to be declared an honorary citizen of a foreign country, and an honorary citizen of France. -John Adams ...' ///Text truncated -"""; -``` - ## Use examples to guide the model An example is text that shows the model how to respond by providing sample user input and model output. The model uses examples to infer what to include in completions. Examples can come either before or after the instructions in an engineered prompt, but the two shouldn't be interspersed. An example starts with a prompt and can optionally include a completion. A completion in an example doesn't have to include the verbatim response—it might just contain a formatted word, the first bullet in an unordered list, or something similar to indicate how each completion should start. -Examples are classified as [zero-shot learning](zero-shot-learning.md) or [few-shot learning](zero-shot-learning.md) based on whether they contain verbatim completions. +Examples are classified as [zero-shot learning](zero-shot-learning.md#zero-shot-learning) or [few-shot learning](zero-shot-learning.md#few-shot-learning) based on whether they contain verbatim completions. - **Zero-shot learning** examples include a prompt with no verbatim completion. This approach tests a model's responses without giving it example data output. Zero-shot prompts can have completions that include cues, such as indicating the model should output an ordered list by including **"1."** as the completion. - **Few-shot learning** examples include several pairs of prompts with verbatim completions. Few-shot learning can change the model's behavior by adding to its existing knowledge. -## Understand cues - -A cue is text that conveys the desired structure or format of output. Like an instruction, a cue isn't processed by the model as if it were user input. Like an example, a cue shows the model what you want instead of telling it what to do. You can add as many cues as you want, so you can iterate to get the result you want. Cues are used with an instruction or an example and should be at the end of the prompt. +## Cues -Suppose you use an instruction to tell the model to produce a list of presidential accomplishments by category, along with supporting content that tells the model what categories to use. You decide that you want the model to produce a nested list with all caps for categories, with each president's accomplishments in each category listed on one line that begins with their name, with presidents listed chronologically. After your instruction and supporting content, you could add three cues to show the model how to structure and format the list: - -```csharp -prompt = """ -Instructions: Summarize US Presidential accomplishments, grouped by category. -Categories: Domestic Policy, US Economy, Foreign Affairs, Space Exploration. -Accomplishments: George Washington -First president of the United States. -First president to have been a military veteran. -First president to be elected to a second term in office. -First president to receive votes from every presidential elector in an election. -First president to fill the entire body of the United States federal judges; including the Supreme Court. -First president to be declared an honorary citizen of a foreign country, and an honorary citizen of France. -John Adams ... /// Text truncated - -DOMESTIC POLICY -- George Washington: -- John Adams: -"""; -``` - -- **DOMESTIC POLICY** shows the model that you want it to start each group with the category in all caps. -- **- George Washington:** shows the model to start each section with George Washington's accomplishments listed on one line. -- **- John Adams:** shows the model that it should list remaining presidents in chronological order. +A *cue* is text that conveys the desired structure or format of output. Like an instruction, a cue isn't processed by the model as if it were user input. Like an example, a cue shows the model what you want instead of telling it what to do. You can add as many cues as you want, so you can iterate to get the result you want. Cues are used with an instruction or an example and should be at the end of the prompt. ## Example prompt using .NET -.NET provides various tools to prompt and chat with different AI models. Use [Semantic Kernel](/semantic-kernel/overview/) to connect to a wide variety of AI models and services, as well as other SDKs such as the official [OpenAI .NET library](https://www.nuget.org/packages/OpenAI-DotNet/). Semantic Kernel includes tools to create prompts with different roles and maintain chat history, as well as many other features. +.NET provides various tools to prompt and chat with different AI models. You can use [Agent Framework](/agent-framework/) to connect to a wide variety of AI models and services. Agent Framework includes tools to create agents with system instructions and maintain conversation state across multiple turns. Consider the following code example: -```csharp -using Microsoft.SemanticKernel; -using Microsoft.SemanticKernel.ChatCompletion; - -// Create a kernel with OpenAI chat completion -#pragma warning disable SKEXP0010 -Kernel kernel = Kernel.CreateBuilder() - .AddOpenAIChatCompletion( - modelId: "phi3:mini", - endpoint: new Uri("http://localhost:11434"), - apiKey: "") - .Build(); - -var aiChatService = kernel.GetRequiredService(); -var chatHistory = new ChatHistory(); -chatHistory.Add( - new ChatMessageContent(AuthorRole.System, "You are a helpful AI Assistant.")); - -while (true) -{ - // Get user prompt and add to chat history - Console.WriteLine("Your prompt:"); - chatHistory.Add(new ChatMessageContent(AuthorRole.User, Console.ReadLine())); - - // Stream the AI response and add to chat history - Console.WriteLine("AI Response:"); - var response = ""; - await foreach (var item in - aiChatService.GetStreamingChatMessageContentsAsync(chatHistory)) - { - Console.Write(item.Content); - response += item.Content; - } - chatHistory.Add(new ChatMessageContent(AuthorRole.Assistant, response)); - Console.WriteLine(); -} -``` - -The preceding code provides examples of the following concepts: - -- Creates a chat history service to prompt the AI model for completions based on author roles. -- Configures the AI with an `AuthorRole.System` message. -- Accepts user input to allow for different types of prompts in the context of an `AuthorRole.User`. -- Asynchronously streams the completion from the AI to provide a dynamic chat experience. - -## Extend your prompt engineering techniques - -You can also increase the power of your prompts with more advanced prompt engineering techniques that are covered in depth in their own articles. - -- LLMs have token input limits that constrain the amount of text you can fit in a prompt. Use [embeddings](embeddings.md) and [vector database solutions](vector-databases.md) to reduce the number of tokens you need to represent a given piece of text. -- LLMs aren't trained on your data unless you train them yourself, which can be costly and time-consuming. Use [retrieval augmented generation (RAG)](rag.md) to make your data available to an LLM without training it. +:::code language="csharp" source="../snippets/prompt-engineering/multi-turn-chat.cs"::: + +The preceding code: + +- Creates an Azure OpenAI client with an endpoint and API key. +- Gets a chat client for the GPT-4o model and converts it to an AI agent. +- Creates an agent session to maintain conversation state across multiple turns. +- Accepts user input in a loop to allow for different types of prompts. +- Asynchronously streams the AI response and displays it to the console. ## Related content -- [Prompt engineering techniques](/azure/ai-services/openai/concepts/advanced-prompt-engineering) -- [Configure prompts in Semantic Kernel](/semantic-kernel/prompts/configure-prompts?tabs=Csharp) +- [Prompt engineering techniques](/azure/ai-foundry/openai/concepts/prompt-engineering) +- [System message design](/azure/ai-services/openai/concepts/advanced-prompt-engineering) diff --git a/docs/ai/conceptual/understanding-openai-functions.md b/docs/ai/conceptual/understanding-openai-functions.md index 4ac7d803a2378..8e191c908356c 100644 --- a/docs/ai/conceptual/understanding-openai-functions.md +++ b/docs/ai/conceptual/understanding-openai-functions.md @@ -43,12 +43,6 @@ Some models support parallel function calling, which enables the model to reques Not all OpenAI models are trained to support function calling. For a list of models that support function calling or parallel function calling, see [OpenAI - Supported Models](https://platform.openai.com/docs/guides/function-calling/supported-models). -## Function calling with the Semantic Kernel SDK - -The [Semantic Kernel SDK](/semantic-kernel/overview/) supports describing which functions are available to your AI [using the `KernelFunction` decorator](/semantic-kernel/agents/plugins/using-the-kernelfunction-decorator?tabs=Csharp#use-the-kernelfunction-decorator-to-define-a-native-function). - -The Kernel builds the `tools` parameter of a request based on your decorators, orchestrates the requested function calls to your code, and returns results back to the model. - ## Token counts Function descriptions are included in the system message of your request to a model. These function descriptions count against your model's [token limit](/azure/ai-services/openai/quotas-limits) and are [included in the cost of the request](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/). @@ -61,5 +55,4 @@ If your request exceeds the model's token limit, try the following modifications ## Related content * [Understanding tokens](understanding-tokens.md) -* [Creating native functions for AI to call](/semantic-kernel/agents/plugins/using-the-kernelfunction-decorator?tabs=Csharp) * [Prompt engineering](prompt-engineering-dotnet.md) diff --git a/docs/ai/conceptual/understanding-tokens.md b/docs/ai/conceptual/understanding-tokens.md index 682f4e9272258..9d9e76d55af4b 100644 --- a/docs/ai/conceptual/understanding-tokens.md +++ b/docs/ai/conceptual/understanding-tokens.md @@ -77,7 +77,7 @@ As training continues, the model adds any new tokens in the training text to its The semantic relationships between the tokens can be analyzed by using these token ID sequences. Multi-valued numeric vectors, known as [embeddings](embeddings.md), are used to represent these relationships. An embedding is assigned to each token based on how commonly it's used together with, or in similar contexts to, the other tokens. -After it's trained, a model can calculate an embedding for text that contains multiple tokens. The model tokenizes the text, then calculates an overall embeddings value based on the learned embeddings of the individual tokens. This technique can be used for semantic document searches or adding [vector stores](/semantic-kernel/concepts/vector-store-connectors/) to an AI. +After it's trained, a model can calculate an embedding for text that contains multiple tokens. The model tokenizes the text, then calculates an overall embeddings value based on the learned embeddings of the individual tokens. This technique can be used for semantic document searches or adding vector stores to an AI. During output generation, the model predicts a vector value for the next token in the sequence. The model then selects the next token from its vocabulary based on this vector value. In practice, the model calculates multiple vectors by using various elements of the previous tokens' embeddings. The model then evaluates all potential tokens from these vectors and selects the most probable one to continue the sequence. diff --git a/docs/ai/conceptual/vector-databases.md b/docs/ai/conceptual/vector-databases.md index 36fbfed5b4f4e..2373efce66156 100644 --- a/docs/ai/conceptual/vector-databases.md +++ b/docs/ai/conceptual/vector-databases.md @@ -41,11 +41,6 @@ Other benefits of the RAG pattern include: - Overcome LLM tokens limits - the heavy lifting is done through the database vector search. - Reduce the costs from frequent fine-tuning on updated data. -## Semantic Kernel vector database solutions - -[!INCLUDE [sk-connectors](../includes/sk-connectors.md)] - ## Related content - [Implement Azure OpenAI with RAG using vector search in a .NET app](../tutorials/tutorial-ai-vector-search.md) -- [More Semantic Kernel .NET connectors](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/src/Connectors) diff --git a/docs/ai/dotnet-ai-ecosystem.md b/docs/ai/dotnet-ai-ecosystem.md index 8195c9407f78f..d410a93e0149a 100644 --- a/docs/ai/dotnet-ai-ecosystem.md +++ b/docs/ai/dotnet-ai-ecosystem.md @@ -14,7 +14,7 @@ The .NET ecosystem provides many powerful tools, libraries, and services to deve ## Microsoft.Extensions.AI libraries -[`Microsoft.Extensions.AI`](microsoft-extensions-ai.md) is a set of core .NET libraries that provide a unified layer of C# abstractions for interacting with AI services, such as small and large language models (SLMs and LLMs), embeddings, and middleware. These APIs were created in collaboration with developers across the .NET ecosystem, including Semantic Kernel. The low-level APIs, such as and , were extracted from Semantic Kernel and moved into the namespace. +[`Microsoft.Extensions.AI`](microsoft-extensions-ai.md) is a set of core .NET libraries that provide a unified layer of C# abstractions for interacting with AI services, such as small and large language models (SLMs and LLMs), embeddings, and middleware. These APIs were created in collaboration with developers across the .NET ecosystem. The low-level APIs, such as and , were extracted from Semantic Kernel and moved into the namespace. `Microsoft.Extensions.AI` provides abstractions that can be implemented by various services, all adhering to the same core concepts. This library is not intended to provide APIs tailored to any specific provider's services. The goal of `Microsoft.Extensions.AI` is to act as a unifying layer within the .NET ecosystem, enabling developers to choose their preferred frameworks and libraries while ensuring seamless integration and collaboration across the ecosystem. @@ -41,9 +41,7 @@ For more information, see the [Microsoft Agent Framework documentation](/agent-f ## Semantic Kernel for .NET -[Semantic Kernel](/semantic-kernel/overview/) is an open-source library that enables AI integration and orchestration capabilities in your .NET apps. Semantic Kernel has a dependency on the `Microsoft.Extensions.AI.Abstractions` package and provides connectors with concrete implementations of and for different services, including OpenAI, Amazon Bedrock, and Google Gemini. - -However, for new applications that require agentic capabilities, multi-agent orchestration, or enterprise-grade observability and security, the recommended framework is [Microsoft Agent Framework](/agent-framework/overview/agent-framework-overview). +[Semantic Kernel](/semantic-kernel/overview/) is an open-source library that enables AI integration and orchestration capabilities in your .NET apps. However, for new applications that require agentic capabilities, multi-agent orchestration, or enterprise-grade observability and security, the recommended framework is [Microsoft Agent Framework](/agent-framework/overview/agent-framework-overview). ## .NET SDKs for building AI apps @@ -54,7 +52,6 @@ Many different SDKs are available to build .NET apps with AI capabilities depend | NuGet package | Supported models | Maintainer or vendor | Documentation | |---------------|------------------|----------------------|--------------| | [Microsoft.Agents.AI.OpenAI](https://www.nuget.org/packages/Microsoft.Agents.AI.OpenAI/) | [OpenAI models](https://platform.openai.com/docs/models/overview)
[Azure OpenAI supported models](/azure/ai-services/openai/concepts/models) | [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) (Microsoft) | [Agent Framework documentation](/agent-framework/overview/agent-framework-overview) | -| [Microsoft.SemanticKernel](https://www.nuget.org/packages/Microsoft.SemanticKernel/) | [OpenAI models](https://platform.openai.com/docs/models/overview)
[Azure OpenAI supported models](/azure/ai-services/openai/concepts/models) | [Semantic Kernel](https://github.com/microsoft/semantic-kernel) (Microsoft) | [Semantic Kernel documentation](/semantic-kernel/) | | [Azure OpenAI SDK](https://www.nuget.org/packages/Azure.AI.OpenAI/) | [Azure OpenAI supported models](/azure/ai-services/openai/concepts/models) | [Azure SDK for .NET](https://github.com/Azure/azure-sdk-for-net) (Microsoft) | [Azure OpenAI services documentation](/azure/ai-services/openai/) | | [OpenAI SDK](https://www.nuget.org/packages/OpenAI/) | [OpenAI supported models](https://platform.openai.com/docs/models) | [OpenAI SDK for .NET](https://github.com/openai/openai-dotnet) (OpenAI) | [OpenAI services documentation](https://platform.openai.com/docs/overview) | diff --git a/docs/ai/evaluation/snippets/evaluate-ai-responses/TestAI.csproj b/docs/ai/evaluation/snippets/evaluate-ai-responses/TestAI.csproj index 4fa191d9e55d5..cb5765bac4c48 100644 --- a/docs/ai/evaluation/snippets/evaluate-ai-responses/TestAI.csproj +++ b/docs/ai/evaluation/snippets/evaluate-ai-responses/TestAI.csproj @@ -11,14 +11,14 @@ - - - - - - + + + + + + - + diff --git a/docs/ai/evaluation/snippets/evaluate-safety/EvaluateResponseSafety.csproj b/docs/ai/evaluation/snippets/evaluate-safety/EvaluateResponseSafety.csproj index 6698d76b405ca..e96ea7a2bac79 100644 --- a/docs/ai/evaluation/snippets/evaluate-safety/EvaluateResponseSafety.csproj +++ b/docs/ai/evaluation/snippets/evaluate-safety/EvaluateResponseSafety.csproj @@ -11,15 +11,15 @@ - - - + + + - - - + + + - + diff --git a/docs/ai/evaluation/snippets/evaluate-with-reporting/TestAIWithReporting.csproj b/docs/ai/evaluation/snippets/evaluate-with-reporting/TestAIWithReporting.csproj index 7c7e529b080b5..d204facae12bd 100644 --- a/docs/ai/evaluation/snippets/evaluate-with-reporting/TestAIWithReporting.csproj +++ b/docs/ai/evaluation/snippets/evaluate-with-reporting/TestAIWithReporting.csproj @@ -11,13 +11,13 @@ - - - - - - - + + + + + + + diff --git a/docs/ai/get-started-app-chat-template.md b/docs/ai/get-started-app-chat-template.md index 31f349944d96e..429702e1e512c 100644 --- a/docs/ai/get-started-app-chat-template.md +++ b/docs/ai/get-started-app-chat-template.md @@ -39,7 +39,7 @@ The architecture of the chat app is shown in the following diagram: - **User interface** - The application's chat interface is a [Blazor WebAssembly](/aspnet/core/blazor/) application. This interface is what accepts user queries, routes request to the application backend, and displays generated responses. - **Backend** - The application backend is an [ASP.NET Core Minimal API](/aspnet/core/fundamentals/minimal-apis/overview). The backend hosts the Blazor static web application and is what orchestrates the interactions among the different services. Services used in this application include: - [**Azure AI Search**](/azure/search/search-what-is-azure-search) – Indexes documents from the data stored in an Azure Storage Account. This makes the documents searchable using [vector search](/azure/search/search-get-started-vector) capabilities. - - [**Azure OpenAI Service**](/azure/ai-services/openai/overview) – Provides the Large Language Models (LLM) to generate responses. [Semantic Kernel](/semantic-kernel/whatissk) is used in conjunction with the Azure OpenAI Service to orchestrate the more complex AI workflows. + - [**Azure OpenAI Service**](/azure/ai-services/openai/overview) – Provides the Large Language Models (LLM) to generate responses. [Microsoft Agent Framework](/agent-framework/overview/agent-framework-overview) is used in conjunction with the Azure OpenAI Service to orchestrate the more complex AI workflows. ## Cost diff --git a/docs/ai/how-to/snippets/hosted-app-auth/hosted-app-auth.csproj b/docs/ai/how-to/snippets/hosted-app-auth/hosted-app-auth.csproj index be3f21fb7bb49..b583f1b80cff6 100644 --- a/docs/ai/how-to/snippets/hosted-app-auth/hosted-app-auth.csproj +++ b/docs/ai/how-to/snippets/hosted-app-auth/hosted-app-auth.csproj @@ -10,9 +10,9 @@ - - - + + + diff --git a/docs/ai/includes/sk-connectors.md b/docs/ai/includes/sk-connectors.md deleted file mode 100644 index c0402ca11d34a..0000000000000 --- a/docs/ai/includes/sk-connectors.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -ms.date: 07/29/2024 -ms.topic: include ---- - -AI applications often use data vector databases and services to improve relevancy and provide customized functionality. Many of these services provide a native SDK for .NET, while others offer a REST service you can connect to through custom code. Semantic Kernel provides an extensible component model that enables you to use different vector stores without needing to learn each SDK. - -Semantic Kernel provides connectors for the following vector databases and services: - -| Vector service | Semantic Kernel connector | .NET SDK | -|-------------------------------|---------------------------|----------| -| Azure AI Search | [Microsoft.SemanticKernel.Connectors.AzureAISearch](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.AzureAISearch) | [Azure.Search.Documents](https://www.nuget.org/packages/Azure.Search.Documents/) | -| Azure Cosmos DB for NoSQL | [Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.AzureCosmosDBNoSQL) | [Microsoft.Azure.Cosmos](https://www.nuget.org/packages/Microsoft.Azure.Cosmos/) | -| Azure Cosmos DB for MongoDB | [Microsoft.SemanticKernel.Connectors.AzureCosmosDBMongoDB](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.AzureCosmosDBMongoDB) | [MongoDb.Driver](https://www.nuget.org/packages/MongoDB.Driver) | -| Azure PostgreSQL Server | [Microsoft.SemanticKernel.Connectors.Postgres](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Postgres) | [Npgsql](https://www.nuget.org/packages/Npgsql/) | -| Azure SQL Database | [Microsoft.SemanticKernel.Connectors.SqlServer](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.SqlServer) | [Microsoft.Data.SqlClient](https://www.nuget.org/packages/Microsoft.Data.SqlClient) | -| Chroma | [Microsoft.SemanticKernel.Connectors.Chroma](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Chroma) | [ChromaDB.Client](https://www.nuget.org/packages/ChromaDB.Client) | -| DuckDB | [Microsoft.SemanticKernel.Connectors.DuckDB](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.DuckDB) | [DuckDB.NET.Data.Full](https://www.nuget.org/packages/DuckDB.NET.Data.Full) | -| Milvus | [Microsoft.SemanticKernel.Connectors.Milvus](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Milvus) | [Milvus.Client](https://www.nuget.org/packages/Milvus.Client) | -| MongoDB Atlas Vector Search | [Microsoft.SemanticKernel.Connectors.MongoDB](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.MongoDB) | [MongoDb.Driver](https://www.nuget.org/packages/MongoDB.Driver) | -| Pinecone | [Microsoft.SemanticKernel.Connectors.Pinecone](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Pinecone) | [REST API](https://docs.pinecone.io/reference/api/introduction) | -| Postgres | [Microsoft.SemanticKernel.Connectors.Postgres](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Postgres) | [Npgsql](https://www.nuget.org/packages/Npgsql/) | -| Qdrant | [Microsoft.SemanticKernel.Connectors.Qdrant](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Qdrant) | [Qdrant.Client](https://www.nuget.org/packages/Qdrant.Client) | -| Redis | [Microsoft.SemanticKernel.Connectors.Redis](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Redis) | [StackExchange.Redis](https://www.nuget.org/packages/StackExchange.Redis) | -| Weaviate | [Microsoft.SemanticKernel.Connectors.Weaviate](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.Weaviate) | [REST API](https://docs.weaviate.io/weaviate/api/rest) | - -To discover .NET SDK and API support, visit the documentation for each respective service. diff --git a/docs/ai/index.yml b/docs/ai/index.yml index 205d6b55a00a1..678b45387b83b 100644 --- a/docs/ai/index.yml +++ b/docs/ai/index.yml @@ -25,10 +25,10 @@ landingContent: links: - text: Develop .NET apps with AI features url: overview.md - - text: Microsoft.Extensions.AI libraries - url: microsoft-extensions-ai.md - text: Microsoft Agent Framework url: /agent-framework/overview/agent-framework-overview?toc=/dotnet/ai/toc.json&bc=/dotnet/ai/toc.json + - text: Microsoft.Extensions.AI libraries + url: microsoft-extensions-ai.md - linkListType: get-started links: - text: Connect to and prompt an AI model @@ -63,28 +63,24 @@ landingContent: links: - text: Authenticate App Service to Azure OpenAI url: how-to/app-service-aoai-auth.md - - text: Authenticate App Service to a vector database - url: how-to/app-service-db-auth.md - - text: Use Redis with the Semantic Kernel SDK - url: how-to/use-redis-for-memory.md - - text: Use custom and local AI models with the Semantic Kernel SDK - url: how-to/work-with-local-models.md - - text: Work with content filtering - url: how-to/work-with-local-models.md + - text: Access data in AI functions + url: how-to/access-data-in-functions.md + - text: Use Microsoft.ML.Tokenizers for text tokenization + url: how-to/use-tokenizers.md # Card - title: Training linkLists: - linkListType: tutorial links: + - text: Develop an AI agent with Microsoft Agent Framework + url: /training/modules/develop-ai-agent-with-semantic-kernel/ - text: Plan and prepare to develop AI solutions on Azure url: /training/modules/prepare-azure-ai-development/ - text: Generate conversations Azure OpenAI completions url: /training/modules/open-ai-dotnet-text-completions - text: .NET enterprise chat sample using RAG url: get-started-app-chat-template.md - - text: Develop generative AI apps with Azure OpenAI and Semantic Kernel - url: /training/paths/develop-ai-agents-azure-open-ai-semantic-kernel-sdk # Card - title: Tutorials diff --git a/docs/ai/overview.md b/docs/ai/overview.md index ef3362204bde4..ed23e161a95cd 100644 --- a/docs/ai/overview.md +++ b/docs/ai/overview.md @@ -33,7 +33,7 @@ Millions of developers use .NET to create applications that run on the web, on m | Google Gemini | Google's multimodal AI models | | Amazon Bedrock | AWS's managed service for foundation models | -Any AI provider that's usable with `Microsoft.Extensions.AI` is also usable with Agent Framework and Semantic Kernel. +Any AI provider that's usable with `Microsoft.Extensions.AI` is also usable with Agent Framework. ## What can you build with AI and .NET? diff --git a/docs/ai/quickstarts/build-chat-app.md b/docs/ai/quickstarts/build-chat-app.md index b8c3cb44bb952..4c4e08a256dd6 100644 --- a/docs/ai/quickstarts/build-chat-app.md +++ b/docs/ai/quickstarts/build-chat-app.md @@ -22,8 +22,6 @@ In this quickstart, you learn how to create a conversational .NET console chat a :::zone-end -[!INCLUDE [semantic-kernel](includes/semantic-kernel.md)] - ## Create the app Complete the following steps to create a .NET console app to connect to an AI model. diff --git a/docs/ai/quickstarts/build-vector-search-app.md b/docs/ai/quickstarts/build-vector-search-app.md index 6e7af69aebc6a..39362176f2aaf 100644 --- a/docs/ai/quickstarts/build-vector-search-app.md +++ b/docs/ai/quickstarts/build-vector-search-app.md @@ -16,7 +16,7 @@ Vector stores, or vector databases, are essential for tasks like semantic search The app uses the and libraries so you can write code using AI abstractions rather than a specific SDK. AI abstractions help create loosely coupled code that allows you to change the underlying AI model with minimal app changes. -[📦 Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions/) is a .NET library developed in collaboration with Semantic Kernel and the broader .NET ecosystem to provide a unified layer of abstractions for interacting with vector stores. The abstractions in `Microsoft.Extensions.VectorData.Abstractions` provide library authors and developers with the following functionality: +[📦 Microsoft.Extensions.VectorData.Abstractions](https://www.nuget.org/packages/Microsoft.Extensions.VectorData.Abstractions/) is a .NET library that provides a unified layer of abstractions for interacting with vector stores. The abstractions in `Microsoft.Extensions.VectorData.Abstractions` provide library authors and developers with the following functionality: - Perform create-read-update-delete (CRUD) operations on vector stores. - Use vector and text search on vector stores. diff --git a/docs/ai/quickstarts/chat-local-model.md b/docs/ai/quickstarts/chat-local-model.md index 808dea2598398..6625a97f32051 100644 --- a/docs/ai/quickstarts/chat-local-model.md +++ b/docs/ai/quickstarts/chat-local-model.md @@ -73,7 +73,7 @@ Complete the following steps to create a .NET console app that connects to your ## Connect to and chat with the AI model -The Semantic Kernel SDK provides many services and features to connect to AI models and manage interactions. In the steps ahead, you'll create a simple app that connects to the local AI and stores conversation history to improve the chat experience. +In the steps ahead, you'll create a simple app that connects to the local AI and stores conversation history to improve the chat experience. 1. Open the _Program.cs_ file and replace the contents of the file with the following code: diff --git a/docs/ai/quickstarts/generate-images.md b/docs/ai/quickstarts/generate-images.md index 761982617c796..aef274e6c69e5 100644 --- a/docs/ai/quickstarts/generate-images.md +++ b/docs/ai/quickstarts/generate-images.md @@ -22,8 +22,6 @@ In this quickstart, you create a .NET console app that uses `OpenAI.Images.Image :::zone-end -[!INCLUDE [semantic-kernel](includes/semantic-kernel.md)] - ## Create the app Complete the following steps to create a .NET console app to connect to an AI model. diff --git a/docs/ai/quickstarts/includes/semantic-kernel.md b/docs/ai/quickstarts/includes/semantic-kernel.md deleted file mode 100644 index e8fd9cd552194..0000000000000 --- a/docs/ai/quickstarts/includes/semantic-kernel.md +++ /dev/null @@ -1,2 +0,0 @@ -> [!NOTE] -> You can also use [Semantic Kernel](/semantic-kernel) to accomplish the tasks in this article. Semantic Kernel is a lightweight, open-source SDK that lets you build AI agents and integrate the latest AI models into your .NET apps. diff --git a/docs/ai/quickstarts/prompt-model.md b/docs/ai/quickstarts/prompt-model.md index 66a91a8b329d8..6d330b6bdec28 100644 --- a/docs/ai/quickstarts/prompt-model.md +++ b/docs/ai/quickstarts/prompt-model.md @@ -22,8 +22,6 @@ In this quickstart, you learn how to create a .NET console chat app to connect t :::zone-end -[!INCLUDE [semantic-kernel](includes/semantic-kernel.md)] - ## Create the app Complete the following steps to create a .NET console app to connect to an AI model. diff --git a/docs/ai/quickstarts/snippets/function-calling/azure-openai/FunctionCallingAI.csproj b/docs/ai/quickstarts/snippets/function-calling/azure-openai/FunctionCallingAI.csproj index 2fbd7a39e5015..2d5d822702278 100644 --- a/docs/ai/quickstarts/snippets/function-calling/azure-openai/FunctionCallingAI.csproj +++ b/docs/ai/quickstarts/snippets/function-calling/azure-openai/FunctionCallingAI.csproj @@ -11,10 +11,10 @@ - - - - + + + + diff --git a/docs/ai/quickstarts/snippets/text-to-image/azure-openai/TextToImageAzureOpenAI.csproj b/docs/ai/quickstarts/snippets/text-to-image/azure-openai/TextToImageAzureOpenAI.csproj index 48498978dabc0..36ae6bb02a155 100644 --- a/docs/ai/quickstarts/snippets/text-to-image/azure-openai/TextToImageAzureOpenAI.csproj +++ b/docs/ai/quickstarts/snippets/text-to-image/azure-openai/TextToImageAzureOpenAI.csproj @@ -9,9 +9,9 @@ - - - + + + diff --git a/docs/ai/snippets/microsoft-extensions-ai/AI.Shared/AI.Shared.csproj b/docs/ai/snippets/microsoft-extensions-ai/AI.Shared/AI.Shared.csproj index c1ef30aab2a4a..cc4c5bd3c2df6 100644 --- a/docs/ai/snippets/microsoft-extensions-ai/AI.Shared/AI.Shared.csproj +++ b/docs/ai/snippets/microsoft-extensions-ai/AI.Shared/AI.Shared.csproj @@ -7,8 +7,8 @@ - - + + diff --git a/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.DependencyInjection/ConsoleAI.DependencyInjection.csproj b/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.DependencyInjection/ConsoleAI.DependencyInjection.csproj index 4d6f39628314d..faaec1d4e5330 100644 --- a/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.DependencyInjection/ConsoleAI.DependencyInjection.csproj +++ b/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.DependencyInjection/ConsoleAI.DependencyInjection.csproj @@ -8,9 +8,9 @@ - - - + + + diff --git a/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.StatelessStateful/ConsoleAI.StatelessStateful.csproj b/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.StatelessStateful/ConsoleAI.StatelessStateful.csproj index ccf51af65d5f9..7d1a7ae06cdb0 100644 --- a/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.StatelessStateful/ConsoleAI.StatelessStateful.csproj +++ b/docs/ai/snippets/microsoft-extensions-ai/ConsoleAI.StatelessStateful/ConsoleAI.StatelessStateful.csproj @@ -8,11 +8,11 @@ - + - + diff --git a/docs/ai/snippets/prompt-engineering/multi-turn-chat.cs b/docs/ai/snippets/prompt-engineering/multi-turn-chat.cs new file mode 100644 index 0000000000000..2099f7180da6c --- /dev/null +++ b/docs/ai/snippets/prompt-engineering/multi-turn-chat.cs @@ -0,0 +1,34 @@ +using Azure; +using Azure.AI.OpenAI; +using Microsoft.Agents.AI; +using OpenAI.Chat; + +string endpoint = "https://.openai.azure.com/"; +string apiKey = ""; + +AIAgent agent = new AzureOpenAIClient( + new Uri(endpoint), + new AzureKeyCredential(apiKey)) + .GetChatClient("gpt-4o") + .AsAIAgent(); + +// Create a session to maintain conversation state. +AgentSession session = await agent.GetNewSessionAsync(); + +while (true) +{ + // Get user prompt. + Console.WriteLine("Your prompt:"); + string? userInput = Console.ReadLine(); + + if (string.IsNullOrWhiteSpace(userInput)) + break; + + // Send prompt to agent and stream response. + Console.WriteLine("AI response:"); + await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(userInput, session)) + { + Console.Write(update.Text); + } + Console.WriteLine(); +} diff --git a/docs/ai/snippets/prompt-engineering/multi-turn-chat.csproj b/docs/ai/snippets/prompt-engineering/multi-turn-chat.csproj new file mode 100644 index 0000000000000..0e266e5e689b7 --- /dev/null +++ b/docs/ai/snippets/prompt-engineering/multi-turn-chat.csproj @@ -0,0 +1,20 @@ + + + + Exe + net10.0 + enable + enable + MultiTurnChat + + + + + + + + + diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 10854c8b08bf6..d143fb13ff37a 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -115,8 +115,8 @@ | Time Series Insights | 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/) | | TimeZone | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Maps.TimeZones/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Maps.TimeZones-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Maps.TimeZones_1.0.0-beta.1/sdk/maps/Azure.Maps.TimeZones/) | | unknown | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.AI.AgentServer.AgentFramework/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/AI.AgentServer.AgentFramework-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.AgentFramework_1.0.0-beta.6/sdk/agentserver/Azure.AI.AgentServer.AgentFramework/) | -| unknown | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.AI.AgentServer.Contracts/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Contracts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Contracts_1.0.0-beta.6/sdk/agentserver/Azure.AI.AgentServer.Contracts/) | -| unknown | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.AI.AgentServer.Core/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Core-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Core_1.0.0-beta.6/sdk/agentserver/Azure.AI.AgentServer.Core/) | +| unknown | NuGet [1.0.0-beta.7](https://www.nuget.org/packages/Azure.AI.AgentServer.Contracts/1.0.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Contracts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Contracts_1.0.0-beta.7/sdk/agentserver/Azure.AI.AgentServer.Contracts/) | +| unknown | NuGet [1.0.0-beta.7](https://www.nuget.org/packages/Azure.AI.AgentServer.Core/1.0.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Core-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Core_1.0.0-beta.7/sdk/agentserver/Azure.AI.AgentServer.Core/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.ContentUnderstanding/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.ContentUnderstanding_1.0.0-beta.1/sdk/contentunderstanding/Azure.AI.ContentUnderstanding/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Language.QuestionAnswering.Authoring/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Language.QuestionAnswering.Authoring-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.Language.QuestionAnswering.Authoring_1.0.0-beta.1/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering.Authoring/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Language.QuestionAnswering.Inference/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Language.QuestionAnswering.Inference-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.Language.QuestionAnswering.Inference_1.0.0-beta.1/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering.Inference/) | @@ -256,7 +256,7 @@ | Resource Management - Dynatrace | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Dynatrace/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Dynatrace-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dynatrace_1.2.0/sdk/dynatrace/Azure.ResourceManager.Dynatrace/) | | Resource Management - Edge Order | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.EdgeOrder/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeOrder-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EdgeOrder_1.1.1/sdk/edgeorder/Azure.ResourceManager.EdgeOrder/) | | Resource Management - Edge Zones | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.EdgeZones/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeZones-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.EdgeZones_1.0.0-beta.2/sdk/edgezones/Azure.ResourceManager.EdgeZones/) | -| Resource Management - Edgeactions | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.EdgeActions/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeActions-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EdgeActions_1.0.0-beta.1/sdk/edgeactions/Azure.ResourceManager.EdgeActions/) | +| Resource Management - Edgeactions | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.EdgeActions/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeActions-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.EdgeActions_1.0.0-beta.2/sdk/edgeactions/Azure.ResourceManager.EdgeActions/) | | Resource Management - Elastic | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Elastic/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Elastic-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Elastic_1.1.0/sdk/elastic/Azure.ResourceManager.Elastic/) | | Resource Management - ElasticSan | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ElasticSan/1.1.0)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ElasticSan/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ElasticSan-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ElasticSan_1.1.0/sdk/elasticsan/Azure.ResourceManager.ElasticSan/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ElasticSan_1.2.0-beta.2/sdk/elasticsan/Azure.ResourceManager.ElasticSan/) | | Resource Management - Energy Services | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.EnergyServices/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.EnergyServices-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EnergyServices_1.0.0-beta.3/sdk/openenergyplatform/Azure.ResourceManager.EnergyServices/) | @@ -538,7 +538,7 @@ | App Service - API Apps Service | NuGet [0.9.64](https://www.nuget.org/packages/Microsoft.Azure.AppService.ApiApps.Service/0.9.64) | | | | Code Analyzers for Durable Functions | NuGet [0.5.0](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.DurableTask.Analyzers/0.5.0) | | GitHub [0.5.0](https://github.com/Azure/azure-functions-durable-extension/tree/Analyzer-v0.3.0/src/WebJobs.Extensions.DurableTask.Analyzers) | | Cosmos DB - BulkExecutor | NuGet [2.5.1-preview](https://www.nuget.org/packages/Microsoft.Azure.CosmosDB.BulkExecutor/2.5.1-preview) | | GitHub [2.5.1-preview](https://github.com/Azure/azure-cosmosdb-bulkexecutor-dotnet-getting-started) | -| Cosmos DB - Direct | NuGet [3.41.3](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.41.3) | | GitHub [3.41.3](https://github.com/Azure/azure-cosmos-dotnet-v3) | +| Cosmos DB - Direct | NuGet [3.42.0](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Direct/3.42.0) | | GitHub [3.42.0](https://github.com/Azure/azure-cosmos-dotnet-v3) | | Cosmos DB - Encryption | NuGet [2.0.3](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/2.0.3)
NuGet [2.1.0-preview4](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption/2.1.0-preview4) | | GitHub [2.0.3](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/releases/encryption/1.0.0-preview4/Microsoft.Azure.Cosmos.Encryption) | | Cosmos DB - Encryption | NuGet [1.0.0-preview07](https://www.nuget.org/packages/Microsoft.Azure.Cosmos.Encryption.Custom/1.0.0-preview07) | | | | Extensions - Caching Cosmos | NuGet [1.8.0](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Cosmos/1.8.0) | | GitHub [1.8.0](https://github.com/Azure/Microsoft.Extensions.Caching.Cosmos/tree/v1.0.0-preview4) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 976f44bba218f..840aaeabc6ea9 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -127,8 +127,8 @@ | Time Series Insights | 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/) | | TimeZone | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Maps.TimeZones/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Maps.TimeZones-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Maps.TimeZones_1.0.0-beta.1/sdk/maps/Azure.Maps.TimeZones/) | | unknown | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.AI.AgentServer.AgentFramework/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/AI.AgentServer.AgentFramework-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.AgentFramework_1.0.0-beta.6/sdk/agentserver/Azure.AI.AgentServer.AgentFramework/) | -| unknown | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.AI.AgentServer.Contracts/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Contracts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Contracts_1.0.0-beta.6/sdk/agentserver/Azure.AI.AgentServer.Contracts/) | -| unknown | NuGet [1.0.0-beta.6](https://www.nuget.org/packages/Azure.AI.AgentServer.Core/1.0.0-beta.6) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Core-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.6](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Core_1.0.0-beta.6/sdk/agentserver/Azure.AI.AgentServer.Core/) | +| unknown | NuGet [1.0.0-beta.7](https://www.nuget.org/packages/Azure.AI.AgentServer.Contracts/1.0.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Contracts-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Contracts_1.0.0-beta.7/sdk/agentserver/Azure.AI.AgentServer.Contracts/) | +| unknown | NuGet [1.0.0-beta.7](https://www.nuget.org/packages/Azure.AI.AgentServer.Core/1.0.0-beta.7) | [docs](/dotnet/api/overview/azure/AI.AgentServer.Core-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.7](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.AgentServer.Core_1.0.0-beta.7/sdk/agentserver/Azure.AI.AgentServer.Core/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.ContentUnderstanding/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.ContentUnderstanding_1.0.0-beta.1/sdk/contentunderstanding/Azure.AI.ContentUnderstanding/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Language.QuestionAnswering.Authoring/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Language.QuestionAnswering.Authoring-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.Language.QuestionAnswering.Authoring_1.0.0-beta.1/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering.Authoring/) | | unknown | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.AI.Language.QuestionAnswering.Inference/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/AI.Language.QuestionAnswering.Inference-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.Language.QuestionAnswering.Inference_1.0.0-beta.1/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering.Inference/) | @@ -271,7 +271,7 @@ | Resource Management - Dynatrace | NuGet [1.2.0](https://www.nuget.org/packages/Azure.ResourceManager.Dynatrace/1.2.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Dynatrace-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Dynatrace_1.2.0/sdk/dynatrace/Azure.ResourceManager.Dynatrace/) | | Resource Management - Edge Order | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.EdgeOrder/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeOrder-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EdgeOrder_1.1.1/sdk/edgeorder/Azure.ResourceManager.EdgeOrder/) | | Resource Management - Edge Zones | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.EdgeZones/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeZones-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.EdgeZones_1.0.0-beta.2/sdk/edgezones/Azure.ResourceManager.EdgeZones/) | -| Resource Management - Edgeactions | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.EdgeActions/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeActions-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EdgeActions_1.0.0-beta.1/sdk/edgeactions/Azure.ResourceManager.EdgeActions/) | +| Resource Management - Edgeactions | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.EdgeActions/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.EdgeActions-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.EdgeActions_1.0.0-beta.2/sdk/edgeactions/Azure.ResourceManager.EdgeActions/) | | Resource Management - Elastic | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.Elastic/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Elastic-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Elastic_1.1.0/sdk/elastic/Azure.ResourceManager.Elastic/) | | Resource Management - ElasticSan | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ElasticSan/1.1.0)
NuGet [1.2.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.ElasticSan/1.2.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.ElasticSan-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ElasticSan_1.1.0/sdk/elasticsan/Azure.ResourceManager.ElasticSan/)
GitHub [1.2.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ElasticSan_1.2.0-beta.2/sdk/elasticsan/Azure.ResourceManager.ElasticSan/) | | Resource Management - Energy Services | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.EnergyServices/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.EnergyServices-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.EnergyServices_1.0.0-beta.3/sdk/openenergyplatform/Azure.ResourceManager.EnergyServices/) | diff --git a/docs/azure/sdk/snippets/aspnetcore-guidance/MinApiSample/MinApiSample.csproj b/docs/azure/sdk/snippets/aspnetcore-guidance/MinApiSample/MinApiSample.csproj index 16aea8f2a6914..f3e9191bd4ae7 100644 --- a/docs/azure/sdk/snippets/aspnetcore-guidance/MinApiSample/MinApiSample.csproj +++ b/docs/azure/sdk/snippets/aspnetcore-guidance/MinApiSample/MinApiSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/docs/azure/sdk/snippets/unit-testing/UnitTestingSampleApp.csproj b/docs/azure/sdk/snippets/unit-testing/UnitTestingSampleApp.csproj index 6760b77851e13..549a9a92a7646 100644 --- a/docs/azure/sdk/snippets/unit-testing/UnitTestingSampleApp.csproj +++ b/docs/azure/sdk/snippets/unit-testing/UnitTestingSampleApp.csproj @@ -10,7 +10,7 @@ - + diff --git a/docs/core/diagnostics/dotnet-debug.md b/docs/core/diagnostics/dotnet-debug.md new file mode 100644 index 0000000000000..b41f2b9c3d67f --- /dev/null +++ b/docs/core/diagnostics/dotnet-debug.md @@ -0,0 +1,297 @@ +--- +title: dotnet-debug diagnostic tool - .NET CLI +description: Learn how to install and use the dotnet-debug CLI tool to attach to live processes and analyze dumps for CoreCLR-based .NET applications. +ms.date: 02/09/2026 +ms.topic: reference +ms.custom: linux-related-content +ai-usage: ai-assisted +--- +# Live process debugging and dump analysis utility (dotnet-debug) + +**This article applies to:** ✔️ `dotnet-debug` version 0.0.710501 and later versions + +> [!NOTE] +> `dotnet-debug` currently only supports CoreCLR-based applications and is not currently supported on macOS. + +## Install + +There are two ways to download and install `dotnet-debug`: + +- **dotnet global tool:** + + To install the latest release version of the `dotnet-debug` [NuGet package](https://www.nuget.org/packages/dotnet-debug), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: + + ```dotnetcli + dotnet tool install --global dotnet-debug + ``` + +- **Direct download:** + + Download the tool executable that matches your platform: + + | OS | Platform | + | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | Windows | [x86](https://aka.ms/dotnet-debug/win-x86) \| [x64](https://aka.ms/dotnet-debug/win-x64) \| [Arm](https://aka.ms/dotnet-debug/win-arm) \| [Arm-x64](https://aka.ms/dotnet-debug/win-arm64) | + | Linux | [x64](https://aka.ms/dotnet-debug/linux-x64) \| [Arm](https://aka.ms/dotnet-debug/linux-arm) \| [Arm64](https://aka.ms/dotnet-debug/linux-arm64) \| [musl-x64](https://aka.ms/dotnet-debug/linux-musl-x64) \| [musl-Arm64](https://aka.ms/dotnet-debug/linux-musl-arm64) | + +## Synopsis + +```console +dotnet-debug [-h|--help] [--version] +``` + +## Description + +The `dotnet-debug` global tool lets you attach to live .NET processes and analyze dump files interactively. Unlike `dotnet-dump`, which focuses on dump collection and offline analysis, `dotnet-debug` is designed for live process inspection. It supports all the same [SOS debugging commands](#debugging-sos-commands) as `dotnet-dump`. + +This tool is useful on platforms like Alpine Linux where a fully working `lldb` isn't available. The `dotnet-debug` tool runs SOS commands to analyze managed state and heap diagnostics, but it isn't a native debugger, so displaying native stack frames isn't supported. + +## Options + +- **`--version`** + + Displays the version of the dotnet-debug utility. + +- **`-h|--help`** + + Shows command-line help. + +## Commands + +| Command | +| ------------------------------------------------- | +| [dotnet-debug attach](#dotnet-debug-attach) | +| [dotnet-debug open-dump](#dotnet-debug-open-dump) | + +## dotnet-debug attach + +Attaches to a live process and starts an interactive shell with debugging commands to explore it. + +### Synopsis + +```console +dotnet-debug attach [-c|--commands ] [--accept-license-agreement] +``` + +### Arguments + +- **``** + + The process ID to attach to and analyze. + +### Options + +- **`-c|--commands `** + + Runs the commands on start. Multiple instances of this parameter can be used in an invocation to chain commands. Commands run in the order they're provided on the command line. If you want `dotnet-debug` to exit after the commands, your last command should be `exit`. + +- **`--accept-license-agreement`** + + Accepts the licensing agreement without prompting. + +### Example + +Attach to a running process with ID 1234: + +```console +$ dotnet-debug attach 1234 +Attaching to process: 1234 ... +Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command. +Type 'quit' or 'exit' to exit the session. +> +``` + +Run a command on attach and then exit: + +```console +dotnet-debug attach 1234 -c clrstack -c exit +``` + +## dotnet-debug open-dump + +Starts an interactive shell with debugging commands to explore a dump file. + +### Synopsis + +```console +dotnet-debug open-dump [-c|--commands] [--accept-license-agreement] +``` + +### Arguments + +- **``** + + The path to the dump file to analyze. + +### Options + +- **`-c|--commands `** + + Runs the commands on start. Multiple instances of this parameter can be used in an invocation to chain commands. Commands run in the order they're provided on the command line. If you want `dotnet-debug` to exit after the commands, your last command should be `exit`. + +- **`--accept-license-agreement`** + + Accepts the licensing agreement without prompting. + +### Example + +Open and analyze a dump file: + +```console +$ dotnet-debug open-dump ./core_20260209_135837 +Loading dump: ./core_20260209_135837 ... +Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command. +Type 'quit' or 'exit' to exit the session. +> +``` + +## Debugging SOS commands + +Both the `attach` and `open-dump` commands bring up an interactive session that accepts the following [SOS commands](#debugging-sos-commands). + +| Command | Function | +|-----------------------------------------------------|----------| +| `analyzeoom` | Displays the info of the last OOM that occurred on an allocation request to the GC heap. | +| `clrmodules` | Lists the managed modules in the process. | +| `clrstack` | Provides a stack trace of managed code only. | +| `clrthreads` | Lists the managed threads that are running. | +| `clru` | Displays an annotated disassembly of a managed method. | +| `d` or `readmemory` | Dumps memory contents. | +| `dbgout` | Enables/disables (`-off`) internal SOS logging. | +| `dso` | Displays all managed objects found within the bounds of the current stack. | +| `dumpalc` | Displays details about a collectible AssemblyLoadContext to which the specified object is loaded. | +| `dumparray` | Displays details about a managed array. | +| `dumpasync` | Displays info about async state machines on the garbage-collected heap. | +| `dumpassembly` | Displays details about an assembly. | +| `dumpclass` | Displays information about the `EEClass` structure at the specified address. | +| `dumpconcurrentdictionary` | Displays concurrent dictionary content. | +| `dumpconcurrentqueue` | Displays concurrent queue content. | +| `dumpdelegate` | Displays information about a delegate. | +| `dumpdomain` | Displays information about the all assemblies within all the AppDomains or the specified one. | +| `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 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. | +| `dumpmt` | Displays information about the method table at the specified address. | +| `dumpobj` | Displays info the object at the specified address. | +| `dumpruntimetypes` | Finds all System.RuntimeType objects in the GC heap and prints the type name and MethodTable they refer to. | +| `dumpsig` | Dumps the signature of a method or field specified by ` `. | +| `dumpsigelem` | Dumps a single element of a signature object. | +| `dumpstackobjects` | Displays all managed objects found within the bounds of the current stack. | +| `dumpvc` | Displays info about the fields of a value class. | +| `eeheap` | Displays info about process memory consumed by internal runtime data structures. | +| `eestack` | Runs `dumpstack` on all threads in the process. | +| `eeversion` | Displays information about the runtime and SOS versions. | +| `ehinfo` | Displays the exception handling blocks in a JIT-ed method. | +| `exit` or `quit` | Exits interactive mode. | +| `finalizequeue` | Displays all objects registered for finalization. | +| `findappdomain` | Attempts to resolve the AppDomain of a GC object. | +| `gchandles` | Displays statistics about garbage collector handles in the process. | +| `gcheapstat` | Displays statistics about garbage collector. | +| `gcinfo` | Displays the JIT GC encoding for a method. | +| `gcroot` | Displays info about references (or roots) to the object at the specified address. | +| `gcwhere` | Displays the location in the GC heap of the specified address. | +| `histclear` | Releases any resources used by the family of Hist commands. | +| `histinit` | Initializes the SOS structures from the stress log saved in the debuggee. | +| `histobj` | Examines all stress log relocation records and displays the chain of garbage collection relocations that might have led to the address passed in as an argument. | +| `histobjfind` | Displays all the log entries that reference the object at the specified address. | +| `histroot` | Displays information related to both promotions and relocations of the specified root. | +| `histstats` | Displays stress log stats. | +| `ip2md` | Displays the `MethodDesc` structure at the specified address in code that has been JIT-compiled. | +| `listnearobj` | Displays the object preceding and succeeding the specified address. | +| `logopen` | Enables console file logging. | +| `logclose` | Disables console file logging. | +| `logging` | Enables/disables internal SOS logging. | +| `lm` or `modules` | Displays the native modules in the process. | +| `name2ee` | Displays the `MethodTable` and `EEClass` structures for the specified type or method in the specified module. | +| `objsize` | Displays the size of the specified object. | +| `parallelstacks` | Displays the merged threads stack similarly to the Visual Studio 'Parallel Stacks' panel. | +| `pathto` | Displays the GC path from `` to ``. | +| `pe` or `printexception` | Displays and formats fields of any object derived from the class at the specified address. | +| `r` or `registers` | Displays the thread's registers. | +| `runtimes` | Lists the runtimes in the target or changes the default runtime. | +| `setclrpath` | Sets the path to load coreclr dac/dbi files using `setclrpath `. | +| `setsymbolserver` | Enables the symbol server support. | +| `sos` | Executes various coreclr debugging commands. Use the syntax `sos `. For more information, use `soshelp`. | +| `soshelp` or `help` | Displays all available commands. | +| `soshelp ` or `help ` | Displays the specified command. | +| `syncblk` | Displays the SyncBlock holder info. | +| `taskstate` | Displays a Task state in a human readable format. | +| `threadpool` | Displays info about the runtime thread pool. | +| `threadpoolqueue` | Displays queued thread pool work items. | +| `threadstate` | Pretty prints the meaning of a threads state. | +| `threads ` or `setthread ` | Sets or displays the current thread ID for the SOS commands. | +| `timerinfo` | Displays information about running timers. | +| `token2ee` | Displays the MethodTable structure and MethodDesc structure for the specified token and module. | +| `traverseheap` | Writes out heap information to a file in a format understood by the CLR Profiler. | +| `verifyheap` | Checks the GC heap for signs of corruption. | +| `verifyobj` | Checks the object that is passed as an argument for signs of corruption. | + +> [!NOTE] +> For more details, see [SOS Debugging Extension for .NET](sos-debugging-extension.md). + +## Use `dotnet-debug` to attach to a live process + +The following example shows how to attach to a running .NET process and investigate a thread pool issue: + +```console +$ dotnet-debug attach 1902 +Attaching to process: 1902 ... +Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command. +Type 'quit' or 'exit' to exit the session. +> +``` + +This action brings up an interactive session that accepts commands like: + +```console +> clrstack +OS Thread Id: 0x573d (0) + Child SP IP Call Site +00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean) +00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) +00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) +00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) +00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) +00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) +``` + +To see an unhandled exception: + +```console +> pe -lines +Exception object: 00007fb18c038590 +Exception type: System.Reflection.TargetInvocationException +Message: Exception has been thrown by the target of an invocation. +InnerException: System.Exception, Use !PrintException 00007FB18C038368 to see more. +StackTrace (generated): +SP IP Function +00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean) +00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 +00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d + +StackTraceString: +HResult: 80131604 +``` + +## `dotnet-debug` vs `dotnet-dump` + +`dotnet-debug` and `dotnet-dump` share the same SOS debugging commands but serve different primary purposes: + +| Feature | `dotnet-debug` | `dotnet-dump` | +| -------------------------- | -------------- | ------------- | +| Attach to a live process | ✔️ | ❌ | +| Collect dumps | ❌ | ✔️ | +| Analyze dump files | ✔️ | ✔️ | +| List .NET processes (`ps`) | ❌ | ✔️ | + +Use `dotnet-debug` when you need to debug a live process interactively. Use `dotnet-dump` when you need to collect dumps or analyze them offline. + +## See also + +- [Dump collection and analysis utility (dotnet-dump)](dotnet-dump.md) +- [SOS Debugging Extension for .NET](sos-debugging-extension.md) +- [Heap analysis tool (dotnet-gcdump)](dotnet-gcdump.md) diff --git a/docs/core/diagnostics/snippets/Metrics/metric-instr.csproj b/docs/core/diagnostics/snippets/Metrics/metric-instr.csproj index 88ff7b7658dda..59b90b9f2c4e3 100644 --- a/docs/core/diagnostics/snippets/Metrics/metric-instr.csproj +++ b/docs/core/diagnostics/snippets/Metrics/metric-instr.csproj @@ -9,7 +9,7 @@ - + diff --git a/docs/core/diagnostics/snippets/MetricsGen/MetricsGen.csproj b/docs/core/diagnostics/snippets/MetricsGen/MetricsGen.csproj index 321ab93a47b4a..415cde5f6fec1 100644 --- a/docs/core/diagnostics/snippets/MetricsGen/MetricsGen.csproj +++ b/docs/core/diagnostics/snippets/MetricsGen/MetricsGen.csproj @@ -8,7 +8,7 @@ - + diff --git a/docs/core/diagnostics/snippets/exception-summary/exception-summary.csproj b/docs/core/diagnostics/snippets/exception-summary/exception-summary.csproj index 861b06cc7a7b7..3541cf7b35fd9 100644 --- a/docs/core/diagnostics/snippets/exception-summary/exception-summary.csproj +++ b/docs/core/diagnostics/snippets/exception-summary/exception-summary.csproj @@ -8,8 +8,8 @@ - - + + diff --git a/docs/core/diagnostics/snippets/health-checks/health-checks.csproj b/docs/core/diagnostics/snippets/health-checks/health-checks.csproj index 529c3dd667a6a..5d6c243566721 100644 --- a/docs/core/diagnostics/snippets/health-checks/health-checks.csproj +++ b/docs/core/diagnostics/snippets/health-checks/health-checks.csproj @@ -8,8 +8,8 @@ - - + + diff --git a/docs/core/diagnostics/snippets/lifetime-health-checks/lifetime-health-checks.csproj b/docs/core/diagnostics/snippets/lifetime-health-checks/lifetime-health-checks.csproj index 1fd24c7bfd860..e0c54af013299 100644 --- a/docs/core/diagnostics/snippets/lifetime-health-checks/lifetime-health-checks.csproj +++ b/docs/core/diagnostics/snippets/lifetime-health-checks/lifetime-health-checks.csproj @@ -8,8 +8,8 @@ - - + + diff --git a/docs/core/diagnostics/snippets/resource-monitoring-with-manual-metrics/resource-monitoring-with-manual-metrics.csproj b/docs/core/diagnostics/snippets/resource-monitoring-with-manual-metrics/resource-monitoring-with-manual-metrics.csproj index 88a2b091caa6c..9744dc6c7fa99 100644 --- a/docs/core/diagnostics/snippets/resource-monitoring-with-manual-metrics/resource-monitoring-with-manual-metrics.csproj +++ b/docs/core/diagnostics/snippets/resource-monitoring-with-manual-metrics/resource-monitoring-with-manual-metrics.csproj @@ -9,12 +9,12 @@ - - - - - - + + + + + + diff --git a/docs/core/diagnostics/snippets/resource-monitoring/resource-monitoring.csproj b/docs/core/diagnostics/snippets/resource-monitoring/resource-monitoring.csproj index cc40b02bd5e54..490e383eae413 100644 --- a/docs/core/diagnostics/snippets/resource-monitoring/resource-monitoring.csproj +++ b/docs/core/diagnostics/snippets/resource-monitoring/resource-monitoring.csproj @@ -8,10 +8,10 @@ - - - - + + + + diff --git a/docs/core/enrichment/snippets/enrichment/Enrichment.csproj b/docs/core/enrichment/snippets/enrichment/Enrichment.csproj index f8ea1c801eecc..6094fa931d3d2 100644 --- a/docs/core/enrichment/snippets/enrichment/Enrichment.csproj +++ b/docs/core/enrichment/snippets/enrichment/Enrichment.csproj @@ -8,10 +8,10 @@ - - - - + + + + diff --git a/docs/core/extensions/snippets/caching/distributed/distributed-apis.csproj b/docs/core/extensions/snippets/caching/distributed/distributed-apis.csproj index 73bae408b7b44..786b359a0a6a9 100644 --- a/docs/core/extensions/snippets/caching/distributed/distributed-apis.csproj +++ b/docs/core/extensions/snippets/caching/distributed/distributed-apis.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/caching/memory-apis/memory-apis.csproj b/docs/core/extensions/snippets/caching/memory-apis/memory-apis.csproj index 20b0c46be1926..2bc20505f3732 100644 --- a/docs/core/extensions/snippets/caching/memory-apis/memory-apis.csproj +++ b/docs/core/extensions/snippets/caching/memory-apis/memory-apis.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/caching/memory-worker/memory-worker.csproj b/docs/core/extensions/snippets/caching/memory-worker/memory-worker.csproj index 2e5cb42fe9bc8..2a776e389f12d 100644 --- a/docs/core/extensions/snippets/caching/memory-worker/memory-worker.csproj +++ b/docs/core/extensions/snippets/caching/memory-worker/memory-worker.csproj @@ -8,9 +8,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/app-lifetime/app-lifetime.csproj b/docs/core/extensions/snippets/configuration/app-lifetime/app-lifetime.csproj index 0655dc61f2da5..d358e5d0e099b 100644 --- a/docs/core/extensions/snippets/configuration/app-lifetime/app-lifetime.csproj +++ b/docs/core/extensions/snippets/configuration/app-lifetime/app-lifetime.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/console-basic/console-basic.csproj b/docs/core/extensions/snippets/configuration/console-basic/console-basic.csproj index 9c569bdd2ee9e..b7e38ac90ff62 100644 --- a/docs/core/extensions/snippets/configuration/console-basic/console-basic.csproj +++ b/docs/core/extensions/snippets/configuration/console-basic/console-basic.csproj @@ -14,8 +14,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/console-binder-gen/console-binder-gen.csproj b/docs/core/extensions/snippets/configuration/console-binder-gen/console-binder-gen.csproj index ff8f23e22c231..bb141ebbea045 100644 --- a/docs/core/extensions/snippets/configuration/console-binder-gen/console-binder-gen.csproj +++ b/docs/core/extensions/snippets/configuration/console-binder-gen/console-binder-gen.csproj @@ -13,10 +13,10 @@ - - - - + + + + diff --git a/docs/core/extensions/snippets/configuration/console-custom-logging/console-custom-logging.csproj b/docs/core/extensions/snippets/configuration/console-custom-logging/console-custom-logging.csproj index f4cf436f57f62..93fa5e1639286 100644 --- a/docs/core/extensions/snippets/configuration/console-custom-logging/console-custom-logging.csproj +++ b/docs/core/extensions/snippets/configuration/console-custom-logging/console-custom-logging.csproj @@ -19,9 +19,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/console-env/console-env.csproj b/docs/core/extensions/snippets/configuration/console-env/console-env.csproj index 95471c7bf4a0b..020603f4016f7 100644 --- a/docs/core/extensions/snippets/configuration/console-env/console-env.csproj +++ b/docs/core/extensions/snippets/configuration/console-env/console-env.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/console-host/console-host.csproj b/docs/core/extensions/snippets/configuration/console-host/console-host.csproj index 5b855b2280d2a..9bc246194b6b7 100644 --- a/docs/core/extensions/snippets/configuration/console-host/console-host.csproj +++ b/docs/core/extensions/snippets/configuration/console-host/console-host.csproj @@ -19,9 +19,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/console-indexer/console-indexer.csproj b/docs/core/extensions/snippets/configuration/console-indexer/console-indexer.csproj index 9c569bdd2ee9e..b7e38ac90ff62 100644 --- a/docs/core/extensions/snippets/configuration/console-indexer/console-indexer.csproj +++ b/docs/core/extensions/snippets/configuration/console-indexer/console-indexer.csproj @@ -14,8 +14,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/console-ini/console-ini.csproj b/docs/core/extensions/snippets/configuration/console-ini/console-ini.csproj index 8d3e041a5f377..7ba243f45615f 100644 --- a/docs/core/extensions/snippets/configuration/console-ini/console-ini.csproj +++ b/docs/core/extensions/snippets/configuration/console-ini/console-ini.csproj @@ -19,9 +19,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/console-json/console-json.csproj b/docs/core/extensions/snippets/configuration/console-json/console-json.csproj index 5ed26b91a9be8..56e326ac72675 100644 --- a/docs/core/extensions/snippets/configuration/console-json/console-json.csproj +++ b/docs/core/extensions/snippets/configuration/console-json/console-json.csproj @@ -19,9 +19,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/console-memory/console-memory.csproj b/docs/core/extensions/snippets/configuration/console-memory/console-memory.csproj index f2124ae45b123..8ee501bbc369c 100644 --- a/docs/core/extensions/snippets/configuration/console-memory/console-memory.csproj +++ b/docs/core/extensions/snippets/configuration/console-memory/console-memory.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/console-raw/console-raw.csproj b/docs/core/extensions/snippets/configuration/console-raw/console-raw.csproj index 1af2a463aa61a..8551c9e2ba817 100644 --- a/docs/core/extensions/snippets/configuration/console-raw/console-raw.csproj +++ b/docs/core/extensions/snippets/configuration/console-raw/console-raw.csproj @@ -14,9 +14,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/console-validation-gen/console-validation-gen.csproj b/docs/core/extensions/snippets/configuration/console-validation-gen/console-validation-gen.csproj index 732282b68ef4a..3af3093cc6969 100644 --- a/docs/core/extensions/snippets/configuration/console-validation-gen/console-validation-gen.csproj +++ b/docs/core/extensions/snippets/configuration/console-validation-gen/console-validation-gen.csproj @@ -19,10 +19,10 @@ - - - - + + + + diff --git a/docs/core/extensions/snippets/configuration/console-xml/console-xml.csproj b/docs/core/extensions/snippets/configuration/console-xml/console-xml.csproj index 7774aec729f08..f6916043bf2e2 100644 --- a/docs/core/extensions/snippets/configuration/console-xml/console-xml.csproj +++ b/docs/core/extensions/snippets/configuration/console-xml/console-xml.csproj @@ -23,9 +23,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/console/console.csproj b/docs/core/extensions/snippets/configuration/console/console.csproj index a43038d661a35..377d97e8bc738 100644 --- a/docs/core/extensions/snippets/configuration/console/console.csproj +++ b/docs/core/extensions/snippets/configuration/console/console.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj b/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj index ab7c42b4674c6..b2dc2ecc3abd0 100644 --- a/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj +++ b/docs/core/extensions/snippets/configuration/custom-provider/custom-provider.csproj @@ -9,11 +9,11 @@ - - - - - + + + + + diff --git a/docs/core/extensions/snippets/configuration/options-action/options-action.csproj b/docs/core/extensions/snippets/configuration/options-action/options-action.csproj index bb1ac6ca202b0..88953be41abeb 100644 --- a/docs/core/extensions/snippets/configuration/options-action/options-action.csproj +++ b/docs/core/extensions/snippets/configuration/options-action/options-action.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/options-configparam/options-configparam.csproj b/docs/core/extensions/snippets/configuration/options-configparam/options-configparam.csproj index 7c72a60ef2462..1dc4bb61434b6 100644 --- a/docs/core/extensions/snippets/configuration/options-configparam/options-configparam.csproj +++ b/docs/core/extensions/snippets/configuration/options-configparam/options-configparam.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/options-noparams/options-noparams.csproj b/docs/core/extensions/snippets/configuration/options-noparams/options-noparams.csproj index 9d5d424d0c50a..3a89c24c00929 100644 --- a/docs/core/extensions/snippets/configuration/options-noparams/options-noparams.csproj +++ b/docs/core/extensions/snippets/configuration/options-noparams/options-noparams.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/options-object/options-object.csproj b/docs/core/extensions/snippets/configuration/options-object/options-object.csproj index 5a222ff2af9bd..3be6ae170fb5a 100644 --- a/docs/core/extensions/snippets/configuration/options-object/options-object.csproj +++ b/docs/core/extensions/snippets/configuration/options-object/options-object.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/options-postconfig/options-postconfig.csproj b/docs/core/extensions/snippets/configuration/options-postconfig/options-postconfig.csproj index a598f6260ad3c..4af507f8e8fbc 100644 --- a/docs/core/extensions/snippets/configuration/options-postconfig/options-postconfig.csproj +++ b/docs/core/extensions/snippets/configuration/options-postconfig/options-postconfig.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/options-validation-onstart/options-validation-onstart.csproj b/docs/core/extensions/snippets/configuration/options-validation-onstart/options-validation-onstart.csproj index ea4d451e095b7..e799fbbeb638d 100644 --- a/docs/core/extensions/snippets/configuration/options-validation-onstart/options-validation-onstart.csproj +++ b/docs/core/extensions/snippets/configuration/options-validation-onstart/options-validation-onstart.csproj @@ -19,9 +19,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj b/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj index 051fb34bf115f..505c37ebc418c 100644 --- a/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj +++ b/docs/core/extensions/snippets/configuration/worker-scope/worker-scope.csproj @@ -8,7 +8,7 @@ - - + + diff --git a/docs/core/extensions/snippets/configuration/worker-service/worker-service.csproj b/docs/core/extensions/snippets/configuration/worker-service/worker-service.csproj index 6d195335b9f8b..ab6daeb38ae76 100644 --- a/docs/core/extensions/snippets/configuration/worker-service/worker-service.csproj +++ b/docs/core/extensions/snippets/configuration/worker-service/worker-service.csproj @@ -9,7 +9,7 @@ - - + + diff --git a/docs/core/extensions/snippets/fileglobbing/example/example.csproj b/docs/core/extensions/snippets/fileglobbing/example/example.csproj index 17e279eea7d9a..cb5f2a4b12303 100644 --- a/docs/core/extensions/snippets/fileglobbing/example/example.csproj +++ b/docs/core/extensions/snippets/fileglobbing/example/example.csproj @@ -59,8 +59,8 @@ - - + + diff --git a/docs/core/extensions/snippets/http/basic/basic.csproj b/docs/core/extensions/snippets/http/basic/basic.csproj index 71a553d76f800..c9f2de248d287 100644 --- a/docs/core/extensions/snippets/http/basic/basic.csproj +++ b/docs/core/extensions/snippets/http/basic/basic.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/http/configurehandler/configurehandler.csproj b/docs/core/extensions/snippets/http/configurehandler/configurehandler.csproj index 7347851f57e47..e64bf964f320f 100644 --- a/docs/core/extensions/snippets/http/configurehandler/configurehandler.csproj +++ b/docs/core/extensions/snippets/http/configurehandler/configurehandler.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/http/generated/generated.csproj b/docs/core/extensions/snippets/http/generated/generated.csproj index 3c226babcc99c..89d0241cf3cdb 100644 --- a/docs/core/extensions/snippets/http/generated/generated.csproj +++ b/docs/core/extensions/snippets/http/generated/generated.csproj @@ -9,9 +9,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/http/latency/latency.csproj b/docs/core/extensions/snippets/http/latency/latency.csproj index c643620bbca20..de92984de0c1d 100644 --- a/docs/core/extensions/snippets/http/latency/latency.csproj +++ b/docs/core/extensions/snippets/http/latency/latency.csproj @@ -18,7 +18,7 @@ - + diff --git a/docs/core/extensions/snippets/http/named/named.csproj b/docs/core/extensions/snippets/http/named/named.csproj index 485cc680c1847..8db0213a06784 100644 --- a/docs/core/extensions/snippets/http/named/named.csproj +++ b/docs/core/extensions/snippets/http/named/named.csproj @@ -19,8 +19,8 @@ - - + + diff --git a/docs/core/extensions/snippets/http/typed/typed.csproj b/docs/core/extensions/snippets/http/typed/typed.csproj index 69c006ce797d7..755ba92d27b41 100644 --- a/docs/core/extensions/snippets/http/typed/typed.csproj +++ b/docs/core/extensions/snippets/http/typed/typed.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/localization/example/example.csproj b/docs/core/extensions/snippets/localization/example/example.csproj index b13978a1bf6a6..7169261772c97 100644 --- a/docs/core/extensions/snippets/localization/example/example.csproj +++ b/docs/core/extensions/snippets/localization/example/example.csproj @@ -9,8 +9,8 @@ - - + + diff --git a/docs/core/extensions/snippets/logging/di-without-host/di-without-host.csproj b/docs/core/extensions/snippets/logging/di-without-host/di-without-host.csproj index 6bb3809b510da..4b125b6ef06d7 100644 --- a/docs/core/extensions/snippets/logging/di-without-host/di-without-host.csproj +++ b/docs/core/extensions/snippets/logging/di-without-host/di-without-host.csproj @@ -9,9 +9,9 @@ - - - + + + diff --git a/docs/core/extensions/snippets/logging/log-sampling/trace-based/LogSamplingTraceBased.csproj b/docs/core/extensions/snippets/logging/log-sampling/trace-based/LogSamplingTraceBased.csproj index 796e639843262..a70b84ef811e2 100644 --- a/docs/core/extensions/snippets/logging/log-sampling/trace-based/LogSamplingTraceBased.csproj +++ b/docs/core/extensions/snippets/logging/log-sampling/trace-based/LogSamplingTraceBased.csproj @@ -8,12 +8,12 @@ - - - + + + - - + + diff --git a/docs/core/extensions/snippets/primitives/change/tokens.csproj b/docs/core/extensions/snippets/primitives/change/tokens.csproj index 7cbd660e433a7..20c13701d0a05 100644 --- a/docs/core/extensions/snippets/primitives/change/tokens.csproj +++ b/docs/core/extensions/snippets/primitives/change/tokens.csproj @@ -9,7 +9,7 @@ - + diff --git a/docs/core/extensions/snippets/primitives/string/tokenizers.csproj b/docs/core/extensions/snippets/primitives/string/tokenizers.csproj index 079560b4571c2..d0f22b1ae867c 100644 --- a/docs/core/extensions/snippets/primitives/string/tokenizers.csproj +++ b/docs/core/extensions/snippets/primitives/string/tokenizers.csproj @@ -10,7 +10,7 @@ - + diff --git a/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibraryTest/StringLibraryTest.vbproj b/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibraryTest/StringLibraryTest.vbproj index 77a91788ca77f..a5bb770f5185b 100644 --- a/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibraryTest/StringLibraryTest.vbproj +++ b/docs/core/tutorials/snippets/library-with-visual-studio/vb/StringLibraryTest/StringLibraryTest.vbproj @@ -8,8 +8,8 @@ - - + + diff --git a/docs/csharp/language-reference/includes/default-langversion-table.md b/docs/csharp/language-reference/includes/default-langversion-table.md index f9185ba55aa01..268b9da577954 100644 --- a/docs/csharp/language-reference/includes/default-langversion-table.md +++ b/docs/csharp/language-reference/includes/default-langversion-table.md @@ -4,6 +4,7 @@ ms.custom: "updateeachrelease" | Target | Version | C# language version default | |------------------|---------|-----------------------------| +| .NET | 11.x | C# 15 | | .NET | 10.x | C# 14 | | .NET | 9.x | C# 13 | | .NET | 8.x | C# 12 | diff --git a/docs/csharp/language-reference/includes/langversion-table.md b/docs/csharp/language-reference/includes/langversion-table.md index d7d81b3b80f23..946050c676652 100644 --- a/docs/csharp/language-reference/includes/langversion-table.md +++ b/docs/csharp/language-reference/includes/langversion-table.md @@ -7,6 +7,7 @@ ms.custom: "updateeachrelease" | `preview` | The compiler accepts all valid language syntax from the latest preview version. | | `latest` | The compiler accepts syntax from the latest released version of the compiler (including minor version). | | `latestMajor`
or `default` | The compiler accepts syntax from the latest released major version of the compiler. | +| `15.0` | The compiler accepts only syntax that is included in C# 15 or lower. | | `14.0` | The compiler accepts only syntax that is included in C# 14 or lower. | | `13.0` | The compiler accepts only syntax that is included in C# 13 or lower. | | `12.0` | The compiler accepts only syntax that is included in C# 12 or lower. | diff --git a/docs/csharp/language-reference/keywords/index.md b/docs/csharp/language-reference/keywords/index.md index 41542291e91ac..2e4f273d6634e 100644 --- a/docs/csharp/language-reference/keywords/index.md +++ b/docs/csharp/language-reference/keywords/index.md @@ -166,7 +166,7 @@ A contextual keyword provides a specific meaning in the code, but it isn't a res [`when` (filter condition)](when.md) [`where` (generic type constraint)](where-generic-type-constraint.md) [`where` (query clause)](where-clause.md) - [`with`](../operators/with-expression.md) + [`with`](with.md) [`yield`](../statements/yield.md) :::column-end::: :::row-end::: diff --git a/docs/csharp/language-reference/keywords/with.md b/docs/csharp/language-reference/keywords/with.md new file mode 100644 index 0000000000000..86aed042beb3c --- /dev/null +++ b/docs/csharp/language-reference/keywords/with.md @@ -0,0 +1,21 @@ +--- +description: "with - C# Reference" +title: "`with` contextual keyword" +ms.date: 02/06/2026 +f1_keywords: + - "with" + - "with_CSharpKeyword" +helpviewer_keywords: + - "with keyword [C#]" +--- + +# `with` (C# reference) + +Use the `with` keyword in the following contexts: + +- In a [`with` expression](../operators/with-expression.md) to create a copy and apply modifications to one or more properties. +- In a [collection expression](../operators/collection-expressions.md) to specify parameters to the constructor for the initialized collection. + +## See also + +- [C# Keywords](index.md) diff --git a/docs/csharp/language-reference/language-versioning.md b/docs/csharp/language-reference/language-versioning.md index ab9665c33cb40..16847f0bbeec1 100644 --- a/docs/csharp/language-reference/language-versioning.md +++ b/docs/csharp/language-reference/language-versioning.md @@ -2,7 +2,7 @@ title: Language versioning description: Learn about how the C# language version is determined based on your project and the reasons behind that choice. ms.custom: "updateeachrelease" -ms.date: 01/16/2026 +ms.date: 02/04/2026 --- # C# language versioning @@ -11,7 +11,7 @@ The latest C# compiler determines a default language version based on your proje [!INCLUDE[csharp-version-note](./includes/initial-version.md)] -[C# 14](../whats-new/csharp-14.md) is supported only on .NET 10 and newer versions. [C# 13](../whats-new/csharp-13.md) is supported only on .NET 9 and newer versions. [C# 12](../whats-new/csharp-12.md) is supported only on .NET 8 and newer versions. Using a C# language version newer than the version associated with your target TFM is unsupported. +[C# 15](../whats-new/csharp-15.md) is supported only on .NET 11 and newer versions. [C# 14](../whats-new/csharp-14.md) is supported only on .NET 10 and newer versions. [C# 13](../whats-new/csharp-13.md) is supported only on .NET 9 and newer versions. Using a C# language version newer than the version associated with your target TFM is unsupported. For details on which .NET versions are supported by versions of Visual Studio, see the [Visual Studio platform compatibility](/visualstudio/releases/2026/compatibility#-visual-studio-support-for-net-development) page. diff --git a/docs/csharp/language-reference/operators/collection-expressions.md b/docs/csharp/language-reference/operators/collection-expressions.md index 5024f70e471f8..f5fb5ebb480ae 100644 --- a/docs/csharp/language-reference/operators/collection-expressions.md +++ b/docs/csharp/language-reference/operators/collection-expressions.md @@ -1,7 +1,7 @@ --- title: "Collection expressions (Collection literals)" description: Collection expressions convert to many collection types. You can write literal values, expressions, or other collections to create a new collection. -ms.date: 01/20/2026 +ms.date: 02/04/2026 helpviewer_keywords: - "Collection expressions" --- @@ -68,18 +68,18 @@ When you convert a collection expression to a `Span` or `ReadOnlySpan`, the span ## Collection builder -Collection expressions work with any collection type that's *well-behaved*. A well-behaved collection has the following characteristics: +Collection expressions work with any collection type that is *well-behaved*. A well-behaved collection has the following characteristics: - The value of `Count` or `Length` on a [countable](./member-access-operators.md#index-from-end-operator-) collection produces the same value as the number of elements when enumerated. -- The types in the namespace are presumed to be side-effect free. As such, the compiler can optimize scenarios where such types might be used as intermediary values, but otherwise aren't exposed. -- A call to some applicable `.AddRange(x)` member on a collection results in the same final value as iterating over `x` and adding all of its enumerated values individually to the collection with `.Add`. +- The types in the namespace are side-effect free. The compiler can optimize scenarios where these types might be used as intermediary values, but it doesn't expose them otherwise. +- A call to an applicable `.AddRange(x)` member on a collection results in the same final value as iterating over `x` and adding all of its enumerated values individually to the collection by using `.Add`. All the collection types in the .NET runtime are well-behaved. > [!WARNING] > If a custom collection type isn't well-behaved, the behavior is undefined when you use that collection type with collection expressions. -Your types opt in to collection expression support by writing a `Create()` method and applying the on the collection type to indicate the builder method. For example, consider an application that uses fixed length buffers of 80 characters. That class might look something like the following code: +Your types opt in to collection expression support by writing a `Create()` method and applying the attribute on the collection type to indicate the builder method. For example, consider an application that uses fixed length buffers of 80 characters. That class might look something like the following code: :::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="BufferDeclaration"::: @@ -91,10 +91,61 @@ The `LineBuffer` type implements `IEnumerable`, so the compiler recognizes :::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="BuilderClass"::: -The `Create` method must return a `LineBuffer` object, and it must take a single parameter of the type `ReadOnlySpan`. The type parameter of the `ReadOnlySpan` must match the element type of the collection. A builder method that returns a generic collection has the generic `ReadOnlySpan` as its parameter. The method must be accessible and `static`. +The `Create` method must return a `LineBuffer` object, and it must take a final parameter of the type `ReadOnlySpan`. The type parameter of the `ReadOnlySpan` must match the element type of the collection. A builder method that returns a generic collection has the generic `ReadOnlySpan` as its parameter. The method must be accessible and `static`. + +Starting in C# 15, the `Create` method can have additional parameters before the `ReadOnlySpan` parameter. You can pass values to these parameters by using a `with(...)` element in the collection expression. See [Collection builder arguments](#collection-builder-arguments) for details. Finally, you must add the to the `LineBuffer` class declaration: :::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="BuilderAttribute"::: The first parameter provides the name of the *Builder* class. The second attribute provides the name of the builder method. + +## Collection expression arguments + +Starting in C# 15, you can pass arguments to the underlying collection's constructor or factory method by using a `with(...)` element as the first element in a collection expression. This feature enables you to specify capacity, comparers, or other constructor parameters directly within the collection expression syntax. For more information, see the [collection expression arguments feature specification](~/_csharplang/proposals/collection-expression-arguments.md). + +The `with(...)` element must be the first element in the collection expression. The arguments declared in the `with(...)` element are passed to the appropriate constructor or create method based on the target type. You can use any valid expression for the arguments in the `with` element. + +### Constructor arguments + +When the target type is a class or struct that implements , the arguments in `with(...)` are evaluated and the results are passed to the constructor. The compiler uses overload resolution to select the best matching constructor: + +:::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="WithArgumentsExamples"::: + +In the preceding example: + +- The `List` constructor with a `capacity` parameter is called with `values.Length * 2`. +- The `HashSet` constructor with an parameter is called with `StringComparer.OrdinalIgnoreCase`. +- For interface target types like , the compiler creates a `List` with the specified capacity. + +### Collection builder arguments + +For types with a , the arguments declared in the `with(...)` element are evaluated and the results are passed to the create method *before* the `ReadOnlySpan` parameter. This feature allows create methods to accept configuration parameters: + +:::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="BuilderClassWithComparer"::: + +You can then use the `with(...)` element to pass the comparer: + +:::code language="csharp" source="./snippets/shared/CollectionExpressionExamples.cs" id="WithBuilderArgumentsExample"::: + +The create method is selected using overload resolution based on the arguments provided. The `ReadOnlySpan` containing the collection elements is always the last parameter. + +### Interface target types + +Several interface target types support collection expression arguments. The following table shows the supported interfaces and their applicable constructor signatures: + +| Interface | Supported `with` elements | +|-----------|---------------------| +| , , | `()` (empty only) | +| , | `()`, `(int capacity)` | + +For and , the compiler uses a with the specified constructor. + +### Restrictions + +The `with(...)` element has the following restrictions: + +- It must be the first element in the collection expression. +- Arguments can't have `dynamic` type. +- It's not supported for arrays or span types (`Span`, `ReadOnlySpan`). diff --git a/docs/csharp/language-reference/operators/snippets/shared/CollectionExpressionExamples.cs b/docs/csharp/language-reference/operators/snippets/shared/CollectionExpressionExamples.cs index a96a8be5a77a9..783035c680c86 100644 --- a/docs/csharp/language-reference/operators/snippets/shared/CollectionExpressionExamples.cs +++ b/docs/csharp/language-reference/operators/snippets/shared/CollectionExpressionExamples.cs @@ -2,7 +2,6 @@ using System.Runtime.CompilerServices; using System.Collections; - // [CollectionBuilder(typeof(LineBufferBuilder), "Create")] // @@ -55,6 +54,35 @@ internal static class LineBufferBuilder } // +// +internal static class MySetBuilder +{ + internal static MySet Create(ReadOnlySpan items) => new MySet(items); + internal static MySet Create(IEqualityComparer comparer, ReadOnlySpan items) => + new MySet(items, comparer); +} +// + +// +[CollectionBuilder(typeof(MySetBuilder), "Create")] +public class MySet : IEnumerable +{ + private readonly HashSet _set; + + public MySet(ReadOnlySpan items, IEqualityComparer? comparer = null) + { + _set = new HashSet(comparer); + foreach (var item in items) + { + _set.Add(item); + } + } + + public IEnumerator GetEnumerator() => _set.GetEnumerator(); + IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); +} +// + public class CollectionExpressionExamples { internal static void Examples() @@ -101,6 +129,24 @@ internal static void Examples() "n", "p", "q", "r", "s", "t", "v", "w", "x", "z"]; string[] alphabet = [.. vowels, .. consonants, "y"]; // + + // Test CollectionArgumentsExamples method + Console.WriteLine("\nTesting collection expressions with arguments:"); + var examples = new CollectionExpressionExamples(); + examples.CollectionArgumentsExamples(); + + // Additional test code for collection expressions with arguments + string[] testValues = ["apple", "banana", "cherry"]; + + // Test List with capacity + List fruits = [with(capacity: testValues.Length * 3), .. testValues]; + Console.WriteLine($"List capacity: {fruits.Capacity}, Count: {fruits.Count}"); + Console.WriteLine($"Fruits: {string.Join(", ", fruits)}"); + + // Test HashSet with comparer + HashSet uniqueWords = [with(StringComparer.OrdinalIgnoreCase), "Hello", "HELLO", "World", "world"]; + Console.WriteLine($"HashSet count (case-insensitive): {uniqueWords.Count}"); + Console.WriteLine($"Unique words: {string.Join(", ", uniqueWords)}"); } @@ -124,5 +170,32 @@ public void Example() } // } + + // + public void CollectionArgumentsExamples() + { + string[] values = ["one", "two", "three"]; + + // Pass capacity argument to List constructor + List names = [with(capacity: values.Length * 2), .. values]; + + // Pass comparer argument to HashSet constructor + HashSet set = [with(StringComparer.OrdinalIgnoreCase), "Hello", "HELLO", "hello"]; + // set contains only one element because all strings are equal with OrdinalIgnoreCase + + // Pass capacity to IList (uses List constructor) + IList numbers = [with(capacity: 100), 1, 2, 3]; + } + // + + // + public void CollectionBuilderArgumentsExample() + { + // Pass comparer to a type with CollectionBuilder attribute + // The comparer argument is passed before the ReadOnlySpan parameter + MySet mySet = [with(StringComparer.OrdinalIgnoreCase), "A", "a", "B"]; + // mySet contains only two elements: "A" and "B" + } + // } diff --git a/docs/csharp/language-reference/operators/snippets/shared/operators.csproj b/docs/csharp/language-reference/operators/snippets/shared/operators.csproj index f4d23c3a13581..5d6cfa5a03119 100644 --- a/docs/csharp/language-reference/operators/snippets/shared/operators.csproj +++ b/docs/csharp/language-reference/operators/snippets/shared/operators.csproj @@ -2,7 +2,8 @@ Exe - net10.0 + net11.0 + preview enable true true diff --git a/docs/csharp/language-reference/operators/with-expression.md b/docs/csharp/language-reference/operators/with-expression.md index 8e71d29fb676d..57dc3f6b62d2d 100644 --- a/docs/csharp/language-reference/operators/with-expression.md +++ b/docs/csharp/language-reference/operators/with-expression.md @@ -2,11 +2,6 @@ title: "The with expression - create new objects that are modified copies of existing objects" description: "Learn about a with expression that performs nondestructive mutation of C# records and structures. The `with` keyword provides the means to modify one or more properties in the new object." ms.date: 01/20/2026 -f1_keywords: - - "with_CSharpKeyword" -helpviewer_keywords: - - "with expression [C#]" - - "with operator [C#]" --- # The `with` expression - Nondestructive mutation creates a new object with modified properties 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 ed0b8890f3cb8..4c66349710ba7 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 @@ -1,31 +1,31 @@ --- -title: "Object and Collection Initializers" +title: "Object and collection initializers" description: Object initializers in C# assign values to accessible fields or properties of an object at creation after invoking a constructor. -ms.date: 10/13/2025 +ms.date: 02/04/2026 helpviewer_keywords: - "object initializers [C#]" - "collection initializers [C#]" --- -# Object and Collection Initializers (C# Programming Guide) +# Object and collection initializers (C# programming guide) -C# lets you instantiate an object or collection and perform member assignments in a single statement. +C# enables you to instantiate an object or collection and perform member assignments in a single statement. ## Object initializers -Object initializers let you assign values to any accessible fields or properties of an object at creation time without having to invoke a constructor followed by lines of assignment statements. The object initializer syntax enables you to specify arguments for a constructor or omit the arguments (and parentheses syntax). The following example shows how to use an object initializer with a named type, `Cat` and how to invoke the parameterless constructor. Note the use of automatically implemented properties in the `Cat` class. For more information, see [Automatically implemented properties](auto-implemented-properties.md). +Object initializers let you assign values to any accessible fields or properties of an object when you create it. You don't need to invoke a constructor and then use assignment statements. The object initializer syntax enables you to specify arguments for a constructor or omit the arguments and parentheses. For guidance on using object initializers consistently, see [Use object initializers (style rule IDE0017)](../../../fundamentals/code-analysis/style-rules/ide0017.md). The following example shows how to use an object initializer with a named type, `Cat`, and how to invoke the parameterless constructor. Note the use of automatically implemented properties in the `Cat` class. For more information, see [Automatically implemented properties](auto-implemented-properties.md). :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="CatDeclaration"::: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="ObjectPropertyInitialization"::: -The object initializers syntax allows you to create an instance, and after that it assigns the newly created object, with its assigned properties, to the variable in the assignment. +The object initializer syntax allows you to create an instance and assign the newly created object, with its assigned properties, to the variable in the assignment. -Starting with nested object properties, you can use object initializer syntax without the `new` keyword. This syntax, `Property = { ... }`, allows you to initialize members of existing nested objects, which is useful with read-only properties. For more information, see [Object Initializers with class-typed properties](#object-initializers-with-class-typed-properties). +Starting with nested object properties, you can use object initializer syntax without the `new` keyword. This syntax, `Property = { ... }`, enables you to initialize members of existing nested objects, which is useful with read-only properties. For more information, see [Object Initializers with class-typed properties](#object-initializers-with-class-typed-properties). Object initializers can set indexers, in addition to assigning fields and properties. Consider this basic `Matrix` class: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="MatrixDeclaration"::: -You could initialize the identity matrix with the following code: +You can initialize the identity matrix by using the following code: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="MatrixInitialization"::: @@ -52,33 +52,33 @@ public char this[int i] { set { ... }; } public string this[char c, int i] { set { ... }; } ``` -## Object Initializers with anonymous types +## Object initializers with anonymous types -Although object initializers can be used in any context, they're especially useful in Language-Integrated Query (LINQ) expressions. Query expressions make frequent use of [anonymous types](../../fundamentals/types/anonymous-types.md), which can only be initialized by using an object initializer, as shown in the following declaration. +Although you can use object initializers in any context, they're especially useful in Language-Integrated Query (LINQ) expressions. Query expressions frequently use [anonymous types](../../fundamentals/types/anonymous-types.md), which you can only initialize by using an object initializer, as shown in the following declaration. ```csharp var pet = new { Age = 10, Name = "Fluffy" }; ``` -Anonymous types enable the `select` clause in a LINQ query expression to transform objects of the original sequence into objects whose value and shape can differ from the original. You might want to store only a part of the information from each object in a sequence. In the following example, assume that a product object (`p`) contains many fields and methods, and that you're only interested in creating a sequence of objects that contain the product name and the unit price. +By using anonymous types, the `select` clause in a LINQ query expression can transform objects of the original sequence into objects whose value and shape differ from the original. You might want to store only a part of the information from each object in a sequence. In the following example, assume that a product object (`p`) contains many fields and methods, and that you're only interested in creating a sequence of objects that contain the product name and the unit price. :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="AnonymousUse"::: -When this query is executed, the `productInfos` variable contains a sequence of objects that can be accessed in a `foreach` statement as shown in this example: +When you execute this query, the `productInfos` variable contains a sequence of objects that you can access in a `foreach` statement as shown in this example: ```csharp foreach(var p in productInfos){...} ``` -Each object in the new anonymous type has two public properties that receive the same names as the properties or fields in the original object. You can also rename a field when you're creating an anonymous type; the following example renames the `UnitPrice` field to `Price`. +Each object in the new anonymous type has two public properties that receive the same names as the properties or fields in the original object. You can also rename a field when you create an anonymous type. The following example renames the `UnitPrice` field to `Price`. ```csharp select new {p.ProductName, Price = p.UnitPrice}; ``` -## Object Initializers with the `required` modifier +## Object initializers with the `required` modifier -You use the `required` keyword to force callers to set the value of a property or field using an object initializer. Required properties don't need to be set as constructor parameters. The compiler ensures all callers initialize those values. +Use the `required` keyword to force callers to set the value of a property or field by using an object initializer. You don't need to set required properties as constructor parameters. The compiler ensures all callers initialize those values. ```csharp public class Pet @@ -98,9 +98,9 @@ var pet = new Pet() { Age = 10}; It's a typical practice to guarantee that your object is properly initialized, especially when you have multiple fields or properties to manage and don't want to include them all in the constructor. -## Object Initializers with the `init` accessor +## Object initializers with the `init` accessor -Making sure no one changes the designed object could be limited by using an `init` accessor. It helps to restrict the setting of the property value. +By using an `init` accessor, you can make sure the object doesn't change after initializtion. It helps to restrict the setting of the property value. ```csharp public class Person @@ -124,12 +124,12 @@ 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 +## Object initializers with class-typed properties -When initializing objects with class-typed properties, you can use two different syntaxes: +When you initialize objects with class-typed properties, you can use two different syntaxes: 1. **Object initializer without `new` keyword**: `Property = { ... }` -2. **Object initializer with `new` keyword**: `Property = new() { ... }` +1. **Object initializer with `new` keyword**: `Property = new() { ... }` These syntaxes behave differently. The following example demonstrates both approaches: @@ -137,7 +137,7 @@ These syntaxes behave differently. The following example demonstrates both appro ### Key differences -- **Without `new` keyword** (`ClassB = { BI = 100003 }`): This syntax modifies the existing instance of the property that was created during object construction. It calls member initializers on the existing object. +- **Without `new` keyword** (`ClassB = { BI = 100003 }`): This syntax modifies the existing instance of the property that the object constructor created. It calls member initializers on the existing object. - **With `new` keyword** (`ClassB = new() { BI = 100003 }`): This syntax creates a new instance and assigns it to the property, replacing any existing instance. @@ -145,7 +145,7 @@ The initializer without `new` reuses the current instance. In the previous examp ### Object initializers without `new` for read-only properties -The syntax without `new` is useful with read-only properties, where you can't assign a new instance but can still initialize the existing instance's members: +The syntax without `new` is useful with read-only properties. You can't assign a new instance but you can still initialize the existing instance's members: :::code language="csharp" source="./snippets/object-collection-initializers/ObjectInitializerWithoutNew.cs" id="ReadOnlyPropertyExample"::: @@ -153,7 +153,7 @@ This approach allows you to initialize nested objects even when the containing p ## 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 value, an expression, or an object initializer. By using a collection initializer, you don't have to specify multiple calls; the compiler adds the calls automatically. +Collection initializers let you specify one or more element initializers when you initialize a collection type that implements and has an `Add` method with the appropriate signature as an instance method or an extension method. The element initializers can be a value, an expression, or an object initializer. By using a collection initializer, you don't have to specify multiple calls; the compiler adds the calls automatically. For guidance on using collection initializers consistently, see [Use collection initializers (style rule IDE0028)](../../../fundamentals/code-analysis/style-rules/ide0028.md). Collection initializers are also useful in [LINQ queries](../../linq/index.md). The following example shows two simple collection initializers: @@ -174,7 +174,7 @@ You can use a spread element to create one list that copies other list or lists. :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="ListInitializerWithSpreadOperator"::: -And include additonal elements along with using a spread element. +And include additional elements along with using a spread element. :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="ListInitializerWithSpreadOperatorAndAdditionalElement"::: @@ -182,19 +182,27 @@ You can specify indexed elements if the collection supports read / write indexin :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="DictionaryIndexerInitializer"::: -The preceding sample generates code that calls the to set the values. You could also initialize dictionaries and other associative containers using the following syntax. Notice that instead of indexer syntax, with parentheses and an assignment, it uses an object with multiple values: +The preceding sample generates code that calls the to set the values. You can also initialize dictionaries and other associative containers by using the following syntax. Instead of indexer syntax, with parentheses and an assignment, it uses an object with multiple values: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="DictionaryAddInitializer"::: This initializer example calls to add the three items into the dictionary. These two different ways to initialize associative collections have slightly different behavior because of the method calls the compiler generates. Both variants work with the `Dictionary` class. Other types might only support one or the other based on their public API. -## Object Initializers with collection read-only property initialization +### Collection expression arguments -Some classes might have collection properties where the property is read-only, like the `Cats` property of `CatOwner` in the following case: +Starting in C# 15, use the `with(...)` element as the first element in a [collection expression](../../language-reference/operators/collection-expressions.md) to pass arguments to the collection's constructor. By using this feature, you can specify capacity, comparers, or other constructor parameters directly within the collection expression syntax: + +:::code language="csharp" source="./snippets/object-collection-initializers/CollectionExpressionArguments.cs" id="CollectionExpressionWithArguments"::: + +For more information about collection expression arguments, including supported target types and restrictions, see [Collection expression arguments](../../language-reference/operators/collection-expressions.md#collection-expression-arguments). + +## Object initializers with collection read-only property initialization + +Some classes have collection properties where the property is read-only, like the `Cats` property of `CatOwner` in the following case: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="CatOwnerDeclaration"::: -You can't use collection initializer syntax discussed so far since the property can't be assigned a new list: +You can't use the collection initializer syntax discussed earlier since the property can't be assigned a new list: ```csharp CatOwner owner = new CatOwner @@ -208,11 +216,11 @@ CatOwner owner = new CatOwner }; ``` -However, new entries can be added to `Cats` nonetheless using the initialization syntax by omitting the list creation (`new List`), as shown next: +However, you can add new entries to `Cats` by using the initialization syntax and omitting the list creation (`new List`), as shown in the following example: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="ReadOnlyPropertyCollectionInitializer"::: -The set of entries to be added appear surrounded by braces. The preceding code is identical to writing: +The set of entries to add appears surrounded by braces. The preceding code is identical to writing: :::code language="csharp" source="./snippets/object-collection-initializers/BasicObjectInitializers.cs" id="ReadOnlyPropertyCollectionInitializerTranslation"::: @@ -226,13 +234,6 @@ The following example shows an object that implements + public static void CollectionExpressionWithArgumentsExample() + { + string[] values = ["one", "two", "three"]; + + // Use with() to pass capacity to the List constructor + List names = [with(capacity: values.Length * 2), .. values]; + + Console.WriteLine($"Created List with capacity: {names.Capacity}"); + Console.WriteLine($"List contains {names.Count} elements: [{string.Join(", ", names)}]"); + + // Use with() to pass a comparer to the HashSet constructor + HashSet caseInsensitiveSet = [with(StringComparer.OrdinalIgnoreCase), "Hello", "HELLO"]; + // caseInsensitiveSet contains only one element because "Hello" and "HELLO" are equal + + Console.WriteLine($"HashSet with case-insensitive comparer contains {caseInsensitiveSet.Count} elements: [{string.Join(", ", caseInsensitiveSet)}]"); + Console.WriteLine("Note: 'Hello' and 'HELLO' are treated as the same element due to OrdinalIgnoreCase comparer"); + } + // +} diff --git a/docs/csharp/programming-guide/classes-and-structs/snippets/object-collection-initializers/object-collection-initializers.csproj b/docs/csharp/programming-guide/classes-and-structs/snippets/object-collection-initializers/object-collection-initializers.csproj index f57e231d581e5..3dd077b3a0f9e 100644 --- a/docs/csharp/programming-guide/classes-and-structs/snippets/object-collection-initializers/object-collection-initializers.csproj +++ b/docs/csharp/programming-guide/classes-and-structs/snippets/object-collection-initializers/object-collection-initializers.csproj @@ -2,7 +2,8 @@ Exe - net8.0 + net11.0 + preview enable enable object_collection_initializers diff --git a/docs/csharp/roslyn-sdk/tutorials/snippets/how-to-write-csharp-analyzer-code-fix/MakeConst/MakeConst.Test/MakeConst.Test.csproj b/docs/csharp/roslyn-sdk/tutorials/snippets/how-to-write-csharp-analyzer-code-fix/MakeConst/MakeConst.Test/MakeConst.Test.csproj index 69e4c492172b6..7597ef8c52d98 100644 --- a/docs/csharp/roslyn-sdk/tutorials/snippets/how-to-write-csharp-analyzer-code-fix/MakeConst/MakeConst.Test/MakeConst.Test.csproj +++ b/docs/csharp/roslyn-sdk/tutorials/snippets/how-to-write-csharp-analyzer-code-fix/MakeConst/MakeConst.Test/MakeConst.Test.csproj @@ -9,7 +9,7 @@ - + diff --git a/docs/csharp/specification/toc.yml b/docs/csharp/specification/toc.yml index bac4c4c1b2468..2286c56360af5 100644 --- a/docs/csharp/specification/toc.yml +++ b/docs/csharp/specification/toc.yml @@ -147,6 +147,8 @@ items: href: ../../../_csharplang/proposals/csharp-12.0/collection-expressions.md - name: Better conversion from collection expression href: ../../../_csharplang/proposals/csharp-13.0/collection-expressions-better-conversion.md + - name: Collection expression arguments + href: ../../../_csharplang/proposals/collection-expression-arguments.md - name: Lambda discard parameters href: ../../../_csharplang/proposals/csharp-9.0/lambda-discard-parameters.md - name: Static anonymous functions diff --git a/docs/csharp/toc.yml b/docs/csharp/toc.yml index 5324dd7a241eb..feb328293414b 100644 --- a/docs/csharp/toc.yml +++ b/docs/csharp/toc.yml @@ -142,6 +142,10 @@ items: href: fundamentals/exceptions/how-to-execute-cleanup-code-using-finally.md - name: What's new in C# items: + - name: C# 15 + items: + - name: What's new in C# 15 + href: whats-new/csharp-15.md - name: C# 14 items: - name: What's new in C# 14 @@ -156,6 +160,8 @@ items: href: whats-new/csharp-12.md - name: Breaking changes items: + - name: After C# 14 + href: ../../_roslyn/docs/compilers/CSharp/Compiler%20Breaking%20Changes%20-%20DotNet%2011.md - name: After C# 13 href: ../../_roslyn/docs/compilers/CSharp/Compiler%20Breaking%20Changes%20-%20DotNet%2010.md - name: After C# 12 diff --git a/docs/csharp/whats-new/csharp-15.md b/docs/csharp/whats-new/csharp-15.md new file mode 100644 index 0000000000000..3b0db85177798 --- /dev/null +++ b/docs/csharp/whats-new/csharp-15.md @@ -0,0 +1,48 @@ +--- +title: What's new in C# 15 +description: Get an overview of the new features in C# 15. C# 15 ships with .NET 11. +ms.date: 02/04/2026 +ms.topic: whats-new +ms.update-cycle: 365-days +ai-usage: ai-assisted +--- +# What's new in C# 15 + +C# 15 includes the following new features. You can try these features using the latest [Visual Studio 2026](https://visualstudio.microsoft.com/) version or the [.NET 11 preview SDK](https://dotnet.microsoft.com/download/dotnet): + +- [Collection expression arguments](#collection-expression-arguments) + +C# 15 is the latest C# release. C# 15 is supported on **.NET 11**. For more information, see [C# language versioning](../language-reference/configure-language-version.md). + +You can download the latest .NET 11 preview SDK from the [.NET downloads page](https://dotnet.microsoft.com/download). You can also download [Visual Studio 2026 insiders](https://visualstudio.microsoft.com/vs/), which includes the .NET 11 preview SDK. + +New features are added to the "What's new in C#" page when they're available in public preview releases. The [working set](https://github.com/dotnet/roslyn/blob/main/docs/Language%20Feature%20Status.md#working-set) section of the [roslyn feature status page](https://github.com/dotnet/roslyn/blob/main/docs/Language%20Feature%20Status.md) tracks when upcoming features are merged into the main branch. + +You can find any breaking changes introduced in C# 15 in our article on [breaking changes](~/_roslyn/docs/compilers/CSharp/Compiler%20Breaking%20Changes%20-%20DotNet%2011.md). + +[!INCLUDE [released-version-feedback](./includes/released-feedback.md)] + +## Collection expression arguments + +You can pass arguments to the underlying collection's constructor or factory method by using a `with(...)` element as the first element in a collection expression. This feature enables you to specify capacity, comparers, or other constructor parameters directly within the collection expression syntax. + +The following example shows how to pass a capacity argument to a `List` constructor and a comparer to a `HashSet`: + +```csharp +string[] values = ["one", "two", "three"]; + +// Pass capacity argument to List constructor +List names = [with(capacity: values.Length * 2), .. values]; + +// Pass comparer argument to HashSet constructor +HashSet set = [with(StringComparer.OrdinalIgnoreCase), "Hello", "HELLO", "hello"]; +// set contains only one element because all strings are equal with OrdinalIgnoreCase +``` + +You can learn more about collection expression arguments in the [language reference article on collection expressions](../language-reference/operators/collection-expressions.md#collection-expression-arguments) or the [feature specification](~/_csharplang/proposals/collection-expression-arguments.md). For information on using collection expression arguments in collection initializers, see [Object and Collection Initializers](../programming-guide/classes-and-structs/object-and-collection-initializers.md#collection-expression-arguments). + + diff --git a/docs/framework/release-notes/2026/01-29-october-cumulative-update-preview.md b/docs/framework/release-notes/2026/01-29-january-cumulative-update-preview.md similarity index 100% rename from docs/framework/release-notes/2026/01-29-october-cumulative-update-preview.md rename to docs/framework/release-notes/2026/01-29-january-cumulative-update-preview.md diff --git a/docs/framework/release-notes/2026/02-10-february-cumulative-update.md b/docs/framework/release-notes/2026/02-10-february-cumulative-update.md new file mode 100644 index 0000000000000..b0a330afe7856 --- /dev/null +++ b/docs/framework/release-notes/2026/02-10-february-cumulative-update.md @@ -0,0 +1,46 @@ +--- +title: February 2026 cumulative update +description: Learn about the improvements in the .NET Framework February 2026 cumulative update. +ms.date: 02/10/2026 +--- +# February 2026 cumulative update + +_Released February 10, 2026_ + +## Summary of what's new in this release + +- [Security improvements](#security-improvements) +- [Quality and reliability improvements](#quality-and-reliability-improvements) + +### Security improvements + +#### CVE-2025-55248 – Information Disclosure vulnerability + +This security update addresses an information disclosure vulnerability detailed in [CVE 2025-55248](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2025-55248). + +### Quality and reliability improvements + +#### .NET Runtime + +Addresses an issue to update operating system calls for compliance with current standards. (*Applies to: .NET Framework 4.8.1*) + +Addresses an issue to add verification logic for ClickOnce to support SHA384 and SHA512. (*Applies to: .NET Framework 4.8.1*) + +Addresses an issue in cases where the Arm64 CLR could crash when code generates and catches a NullReferenceException within the same function. (*Applies to: .NET Framework 4.8.1*) + +## Known issues in this release + +This release contains no known issues. + +## Summary tables + +The following table outlines the updates in this release. + +| Product version | Cumulative update preview | +| --- | --- | +| **Windows 11, version 26H1** | | +| .NET Framework 4.8.1 | [5074837][kbLink] | + +The operating system row lists a KB that's used for update offering purposes. When the operating system KB is offered, the applicability logic determines the specific .NET Framework update(s) installed. Updates for individual .NET Framework versions are installed based on the version of .NET Framework that is already present on the device. Because of this, the operating system KB is not expected to be listed as installed updates on the device. The expected updates installed are the .NET Framework-specific version updates listed in the previous table. + +[kbLink]: https://support.microsoft.com/kb/5074837 diff --git a/docs/framework/release-notes/release-notes.md b/docs/framework/release-notes/release-notes.md index 4186f544356ed..af4c6d43d6adf 100644 --- a/docs/framework/release-notes/release-notes.md +++ b/docs/framework/release-notes/release-notes.md @@ -11,7 +11,8 @@ The .NET Framework updates include cumulative security and reliability improveme .NET Framework cumulative update releases are discussed in detail in the following individual release notes: -* January 29, 2026 - [cumulative update preview](./2026/01-29-october-cumulative-update-preview.md) **New Release** +* February 10, 2026 - [cumulative update](./2026/02-10-february-cumulative-update.md) **New Release** +* January 29, 2026 - [cumulative update preview](./2026/01-29-january-cumulative-update-preview.md) **New Release** * October 28, 2025 - [cumulative update preview](./2025/10-28-october-cumulative-update-preview.md) * October 14, 2025 - [cumulative update](./2025/10-14-october-cumulative-update.md) * September 9, 2025 - [cumulative update](./2025/09-09-september-cumulative-update.md) diff --git a/docs/framework/toc.yml b/docs/framework/toc.yml index ba053f8c1f783..e7545e57c654a 100644 --- a/docs/framework/toc.yml +++ b/docs/framework/toc.yml @@ -714,7 +714,9 @@ items: - name: October 2025 cumulative update preview href: release-notes/2025/10-28-october-cumulative-update-preview.md - name: January 2026 cumulative update preview - href: release-notes/2026/01-29-october-cumulative-update-preview.md + href: release-notes/2026/01-29-january-cumulative-update-preview.md + - name: February 2026 cumulative update + href: release-notes/2026/02-10-february-cumulative-update.md - name: What's new href: whats-new/index.md - name: What's new in accessibility diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index cb89f696e5400..df17213338e4f 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -573,6 +573,8 @@ items: href: ../../core/diagnostics/dotnet-counters.md - name: dotnet-coverage href: ../../core/additional-tools/dotnet-coverage.md + - name: dotnet-debug + href: ../../core/diagnostics/dotnet-debug.md - name: dotnet-dump href: ../../core/diagnostics/dotnet-dump.md - name: dotnet-gcdump diff --git a/docs/orleans/Directory.Build.props b/docs/orleans/Directory.Build.props index 2f89158e72098..bd91b95ac5e98 100644 --- a/docs/orleans/Directory.Build.props +++ b/docs/orleans/Directory.Build.props @@ -13,11 +13,11 @@ - - - + + + - + diff --git a/docs/orleans/grains/grain-persistence/dynamodb-storage.md b/docs/orleans/grains/grain-persistence/dynamodb-storage.md index 45901bd959fce..a981f81e56e91 100644 --- a/docs/orleans/grains/grain-persistence/dynamodb-storage.md +++ b/docs/orleans/grains/grain-persistence/dynamodb-storage.md @@ -1,8 +1,10 @@ --- title: Amazon DynamoDB grain persistence description: Learn about Amazon DynamoDB grain persistence in .NET Orleans. -ms.date: 05/23/2025 +ms.date: 02/06/2026 ms.topic: how-to +ai-usage: ai-assisted +zone_pivot_groups: orleans-version --- # Amazon DynamoDB grain persistence @@ -51,6 +53,30 @@ This configuration allows for both types of authentication credentials: - access key & secret key - access key & secret key & token +:::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" + +``` csharp +siloBuilder.AddDynamoDBGrainStorage( + name: "profileStore", + configureOptions: options => + { + options.AccessKey = "***"; + options.SecretKey = "***"; + options.Service = "***"; + options.ProfileName = "***"; + options.Token = "***"; + }); +``` + +For more information on AWS credentials and named profiles, see [AWS Credentials](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html#creds-locate) and [Named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles) in the AWS documentation. + +## Configure serialization + +Grain storage serialization is configured using the interface. By default, grain state serializes using `Newtonsoft.Json`. You can customize the serializer by setting the property. For more information on configuring grain storage serializers, see [Grain storage serializers](../../host/configuration-guide/serialization.md#grain-storage-serializers). + +:::zone-end +:::zone target="docs" pivot="orleans-3-x" + ``` csharp siloBuilder.AddDynamoDBGrainStorage( name: "profileStore", @@ -66,3 +92,5 @@ siloBuilder.AddDynamoDBGrainStorage( ``` For more information on AWS credentials and named profiles, see [AWS Credentials](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html#creds-locate) and [Named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles) in the AWS documentation. + +:::zone-end diff --git a/docs/orleans/grains/grain-persistence/index.md b/docs/orleans/grains/grain-persistence/index.md index 58594bd8b6f83..5f193fb402c38 100644 --- a/docs/orleans/grains/grain-persistence/index.md +++ b/docs/orleans/grains/grain-persistence/index.md @@ -1,10 +1,11 @@ --- title: Grain persistence description: Learn about grain persistence in .NET Orleans. -ms.date: 05/23/2025 +ms.date: 02/06/2026 ms.topic: overview zone_pivot_groups: orleans-version ms.custom: sfi-ropc-nochange +ai-usage: ai-assisted --- # Grain persistence @@ -200,8 +201,17 @@ Grains executing error-handling or recovery code *must* catch exceptions or faul ### Use JSON serialization or another version-tolerant serialization format +:::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" + +Code evolves, and this often includes storage types. To accommodate these changes, configure an appropriate serializer. Starting with Orleans 7.0, you can configure the grain storage serializer using the interface. By default, grain state serializes using JSON (`Newtonsoft.Json`). Ensure that when evolving data contracts, already-stored data can still be loaded. For more information, see [Grain storage serializers](../../host/configuration-guide/serialization.md#grain-storage-serializers). + +:::zone-end +:::zone target="docs" pivot="orleans-3-x" + Code evolves, and this often includes storage types. To accommodate these changes, configure an appropriate serializer. For most storage providers, a `UseJson` option or similar is available to use JSON as the serialization format. Ensure that when evolving data contracts, already-stored data can still be loaded. +:::zone-end + ## Using to add storage to a grain > [!IMPORTANT] diff --git a/docs/orleans/grains/grain-persistence/relational-storage.md b/docs/orleans/grains/grain-persistence/relational-storage.md index cdcc457dafa9d..0b679ecb7661b 100644 --- a/docs/orleans/grains/grain-persistence/relational-storage.md +++ b/docs/orleans/grains/grain-persistence/relational-storage.md @@ -1,9 +1,11 @@ --- title: ADO.NET grain persistence description: Learn about ADO.NET grain persistence in .NET Orleans. -ms.date: 01/21/2026 +ms.date: 02/06/2026 ms.topic: how-to ms.custom: sfi-ropc-nochange +ai-usage: ai-assisted +zone_pivot_groups: orleans-version --- # ADO.NET grain persistence @@ -31,6 +33,107 @@ Install-Package Microsoft.Orleans.Persistence.AdoNet Read the [ADO.NET configuration](../../host/configuration-guide/adonet-configuration.md) article for information on configuring your database, including the corresponding ADO.NET Invariant and setup scripts. +:::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" + +The following example shows how to configure an ADO.NET storage provider via the silo builder: + +```csharp +var builder = Host.CreateApplicationBuilder(args); +builder.UseOrleans(siloBuilder => +{ + siloBuilder.AddAdoNetGrainStorage("OrleansStorage", options => + { + options.Invariant = ""; + options.ConnectionString = ""; + }); +}); + +using var host = builder.Build(); +await host.RunAsync(); +``` + +Essentially, you only need to set the database-vendor-specific connection string and an `Invariant` (see [ADO.NET Configuration](../../host/configuration-guide/adonet-configuration.md)) identifying the vendor. + +## Configure serialization + +Grain storage serialization is configured using the interface. By default, grain state serializes using `Newtonsoft.Json`. You can customize the serializer by setting the property. + +The following example demonstrates configuring a custom serializer. Your custom serializer (for example, `MyCustomSerializer`) must implement and be registered in the dependency injection container: + +```csharp +// Register your custom serializer in DI +siloBuilder.Services.AddSingleton(); + +// Configure the storage provider to use your serializer +siloBuilder.AddAdoNetGrainStorage( + "OrleansStorage", + (OptionsBuilder optionsBuilder) => + { + optionsBuilder.Configure( + (options, serializer) => + { + options.Invariant = ""; + options.ConnectionString = ""; + options.GrainStorageSerializer = serializer; + }); + }); +``` + +For more information on configuring grain storage serializers, see [Grain storage serializers](../../host/configuration-guide/serialization.md#grain-storage-serializers). + +You can set the following properties via : + +```csharp +/// +/// Options for AdoNetGrainStorage +/// +public class AdoNetGrainStorageOptions +{ + /// + /// Connection string for AdoNet storage. + /// + [Redact] + public string ConnectionString { get; set; } + + /// + /// Stage of silo lifecycle where storage should be initialized. + /// Storage must be initialized prior to use. + /// + public int InitStage { get; set; } = DEFAULT_INIT_STAGE; + + /// + /// Default init stage in silo lifecycle. + /// + public const int DEFAULT_INIT_STAGE = + ServiceLifecycleStage.ApplicationServices; + + /// + /// The default ADO.NET invariant used for storage if none is given. + /// + public const string DEFAULT_ADONET_INVARIANT = + AdoNetInvariants.InvariantNameSqlServer; + + /// + /// The invariant name for storage. + /// + public string Invariant { get; set; } = + DEFAULT_ADONET_INVARIANT; + + /// + /// The grain storage serializer. + /// + public IGrainStorageSerializer GrainStorageSerializer { get; set; } + + /// + /// Gets or sets the hasher picker to use for this storage provider. + /// + public IStorageHasherPicker HashPicker { get; set; } +} +``` + +:::zone-end +:::zone target="docs" pivot="orleans-3-x" + The following example shows how to configure an ADO.NET storage provider via the silo builder: ```csharp @@ -111,6 +214,8 @@ public class AdoNetGrainStorageOptions The ADO.NET persistence provider can version data and define arbitrary (de)serializers with custom application rules and streaming, but currently, there's no method to expose this functionality directly to application code. +:::zone-end + ## ADO.NET persistence rationale The principles for ADO.NET-backed persistence storage are: @@ -137,9 +242,16 @@ This allows you to choose a serialization format, for example, [Simple Binary En - - -After implementing the serializers, add them to the property in . `StorageSerializationPicker` is the default implementation of `IStorageSerializationPicker`. You can see an example of changing the data storage format or using serializers in [RelationalStorageTests](https://github.com/dotnet/orleans/blob/main/test/Extensions/TesterAdoNet/StorageTests/Relational/RelationalStorageTests.cs). +:::zone target="docs" pivot="orleans-7-0,orleans-8-0,orleans-9-0,orleans-10-0" + +After implementing a custom serializer, configure it using the property as described in the [Configure serialization](#configure-serialization) section above. Your custom serializer must implement . + +:::zone-end +:::zone target="docs" pivot="orleans-3-x" + +After implementing the serializers, they're registered internally with the property in . `StorageSerializationPicker` is the default implementation of `IStorageSerializationPicker`. You can see an example of changing the data storage format or using serializers in [RelationalStorageTests](https://github.com/dotnet/orleans/blob/main/test/Extensions/TesterAdoNet/StorageTests/Relational/RelationalStorageTests.cs). Note that direct application-level access to `AdoNetGrainStorage` to configure serialization isn't available in Orleans 3.x. -Currently, there's no method to expose the serialization picker to the Orleans application, as there's no way to access the framework-created `AdoNetGrainStorage` instance directly. +:::zone-end ## Design goals diff --git a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Client/BroadcastChannel.Client.csproj b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Client/BroadcastChannel.Client.csproj index 9245a7444d34f..2e487f4822581 100644 --- a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Client/BroadcastChannel.Client.csproj +++ b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Client/BroadcastChannel.Client.csproj @@ -6,8 +6,8 @@ - - + + diff --git a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.GrainInterfaces/BroadcastChannel.GrainInterfaces.csproj b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.GrainInterfaces/BroadcastChannel.GrainInterfaces.csproj index 86baee7abce31..113a37b3f6958 100644 --- a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.GrainInterfaces/BroadcastChannel.GrainInterfaces.csproj +++ b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.GrainInterfaces/BroadcastChannel.GrainInterfaces.csproj @@ -2,7 +2,7 @@ - + diff --git a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj index 92f919b4e49db..f089e06ab6d5a 100644 --- a/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj +++ b/docs/orleans/streaming/snippets/broadcastchannel/BroadcastChannel.Silo/BroadcastChannel.Silo.csproj @@ -5,11 +5,11 @@ - + - - - + + + diff --git a/samples/snippets/core/testing/unit-testing-vb-mstest/vb/PrimeService.Tests/PrimeService.Tests.vbproj b/samples/snippets/core/testing/unit-testing-vb-mstest/vb/PrimeService.Tests/PrimeService.Tests.vbproj index 69f01cd60d81e..bcc30f990a4f1 100644 --- a/samples/snippets/core/testing/unit-testing-vb-mstest/vb/PrimeService.Tests/PrimeService.Tests.vbproj +++ b/samples/snippets/core/testing/unit-testing-vb-mstest/vb/PrimeService.Tests/PrimeService.Tests.vbproj @@ -8,8 +8,8 @@ - - + + diff --git a/samples/snippets/standard/data/sqlite/AggregateFunctionSample/AggregateFunctionSample.csproj b/samples/snippets/standard/data/sqlite/AggregateFunctionSample/AggregateFunctionSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/AggregateFunctionSample/AggregateFunctionSample.csproj +++ b/samples/snippets/standard/data/sqlite/AggregateFunctionSample/AggregateFunctionSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/AsyncSample/AsyncSample.csproj b/samples/snippets/standard/data/sqlite/AsyncSample/AsyncSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/AsyncSample/AsyncSample.csproj +++ b/samples/snippets/standard/data/sqlite/AsyncSample/AsyncSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/BackupSample/BackupSample.csproj b/samples/snippets/standard/data/sqlite/BackupSample/BackupSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/BackupSample/BackupSample.csproj +++ b/samples/snippets/standard/data/sqlite/BackupSample/BackupSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/BatchingSample/BatchingSample.csproj b/samples/snippets/standard/data/sqlite/BatchingSample/BatchingSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/BatchingSample/BatchingSample.csproj +++ b/samples/snippets/standard/data/sqlite/BatchingSample/BatchingSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/BulkInsertSample/BulkInsertSample.csproj b/samples/snippets/standard/data/sqlite/BulkInsertSample/BulkInsertSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/BulkInsertSample/BulkInsertSample.csproj +++ b/samples/snippets/standard/data/sqlite/BulkInsertSample/BulkInsertSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/CollationSample/CollationSample.csproj b/samples/snippets/standard/data/sqlite/CollationSample/CollationSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/CollationSample/CollationSample.csproj +++ b/samples/snippets/standard/data/sqlite/CollationSample/CollationSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/DapperSample/DapperSample.csproj b/samples/snippets/standard/data/sqlite/DapperSample/DapperSample.csproj index c16561fdcfe86..a04dc13e2e3b1 100644 --- a/samples/snippets/standard/data/sqlite/DapperSample/DapperSample.csproj +++ b/samples/snippets/standard/data/sqlite/DapperSample/DapperSample.csproj @@ -8,7 +8,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/DateAndTimeSample/DateAndTimeSample.csproj b/samples/snippets/standard/data/sqlite/DateAndTimeSample/DateAndTimeSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/DateAndTimeSample/DateAndTimeSample.csproj +++ b/samples/snippets/standard/data/sqlite/DateAndTimeSample/DateAndTimeSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/DeferredTransactionSample/DeferredTransactionSample.csproj b/samples/snippets/standard/data/sqlite/DeferredTransactionSample/DeferredTransactionSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/DeferredTransactionSample/DeferredTransactionSample.csproj +++ b/samples/snippets/standard/data/sqlite/DeferredTransactionSample/DeferredTransactionSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/DirtyReadSample/DirtyReadSample.csproj b/samples/snippets/standard/data/sqlite/DirtyReadSample/DirtyReadSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/DirtyReadSample/DirtyReadSample.csproj +++ b/samples/snippets/standard/data/sqlite/DirtyReadSample/DirtyReadSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/EncryptionSample/EncryptionSample.csproj b/samples/snippets/standard/data/sqlite/EncryptionSample/EncryptionSample.csproj index 2c91afdea3f60..075062010833f 100644 --- a/samples/snippets/standard/data/sqlite/EncryptionSample/EncryptionSample.csproj +++ b/samples/snippets/standard/data/sqlite/EncryptionSample/EncryptionSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/ExtensionsSample/ExtensionsSample.csproj b/samples/snippets/standard/data/sqlite/ExtensionsSample/ExtensionsSample.csproj index a322b492ed341..2e6ed753e2e77 100644 --- a/samples/snippets/standard/data/sqlite/ExtensionsSample/ExtensionsSample.csproj +++ b/samples/snippets/standard/data/sqlite/ExtensionsSample/ExtensionsSample.csproj @@ -7,9 +7,9 @@ - + - + diff --git a/samples/snippets/standard/data/sqlite/HelloWorldSample/HelloWorldSample.csproj b/samples/snippets/standard/data/sqlite/HelloWorldSample/HelloWorldSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/HelloWorldSample/HelloWorldSample.csproj +++ b/samples/snippets/standard/data/sqlite/HelloWorldSample/HelloWorldSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/InteropSample/InteropSample.csproj b/samples/snippets/standard/data/sqlite/InteropSample/InteropSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/InteropSample/InteropSample.csproj +++ b/samples/snippets/standard/data/sqlite/InteropSample/InteropSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/RegularExpressionSample/RegularExpressionSample.csproj b/samples/snippets/standard/data/sqlite/RegularExpressionSample/RegularExpressionSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/RegularExpressionSample/RegularExpressionSample.csproj +++ b/samples/snippets/standard/data/sqlite/RegularExpressionSample/RegularExpressionSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/ResultMetadataSample/ResultMetadataSample.csproj b/samples/snippets/standard/data/sqlite/ResultMetadataSample/ResultMetadataSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/ResultMetadataSample/ResultMetadataSample.csproj +++ b/samples/snippets/standard/data/sqlite/ResultMetadataSample/ResultMetadataSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/SavepointSample/SavepointSample.csproj b/samples/snippets/standard/data/sqlite/SavepointSample/SavepointSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/SavepointSample/SavepointSample.csproj +++ b/samples/snippets/standard/data/sqlite/SavepointSample/SavepointSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/ScalarFunctionSample/ScalarFunctionSample.csproj b/samples/snippets/standard/data/sqlite/ScalarFunctionSample/ScalarFunctionSample.csproj index 7c0c4456e0c36..9cf94fe7242fd 100644 --- a/samples/snippets/standard/data/sqlite/ScalarFunctionSample/ScalarFunctionSample.csproj +++ b/samples/snippets/standard/data/sqlite/ScalarFunctionSample/ScalarFunctionSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/SqliteProviderSample/SqliteProviderSample.csproj b/samples/snippets/standard/data/sqlite/SqliteProviderSample/SqliteProviderSample.csproj index 66a863d8580b4..4d392b43a2d2a 100644 --- a/samples/snippets/standard/data/sqlite/SqliteProviderSample/SqliteProviderSample.csproj +++ b/samples/snippets/standard/data/sqlite/SqliteProviderSample/SqliteProviderSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/StreamingSample/StreamingSample.csproj b/samples/snippets/standard/data/sqlite/StreamingSample/StreamingSample.csproj index 1984ac36ae8a4..14b0e1bc7837d 100644 --- a/samples/snippets/standard/data/sqlite/StreamingSample/StreamingSample.csproj +++ b/samples/snippets/standard/data/sqlite/StreamingSample/StreamingSample.csproj @@ -7,7 +7,7 @@ - + diff --git a/samples/snippets/standard/data/sqlite/SystemLibrarySample/SystemLibrarySample.csproj b/samples/snippets/standard/data/sqlite/SystemLibrarySample/SystemLibrarySample.csproj index 13c156c075a44..97641ad43b69c 100644 --- a/samples/snippets/standard/data/sqlite/SystemLibrarySample/SystemLibrarySample.csproj +++ b/samples/snippets/standard/data/sqlite/SystemLibrarySample/SystemLibrarySample.csproj @@ -7,7 +7,7 @@ - +