diff --git a/docs/ai/dotnet-ai-ecosystem.md b/docs/ai/dotnet-ai-ecosystem.md index fa8b677076a2d..b5448d3fd81c2 100644 --- a/docs/ai/dotnet-ai-ecosystem.md +++ b/docs/ai/dotnet-ai-ecosystem.md @@ -1,7 +1,7 @@ --- title: .NET + AI ecosystem tools and SDKs description: This article provides an overview of the ecosystem of SDKs and tools available to .NET developers integrating AI into their applications. -ms.date: 05/29/2025 +ms.date: 11/04/2025 ms.topic: overview --- @@ -18,19 +18,26 @@ The .NET ecosystem provides many powerful tools, libraries, and services to deve `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. -## Semantic Kernel for .NET +## Microsoft Agent Framework + +If you want to use low-level services, such as and , you can reference the `Microsoft.Extensions.AI.Abstractions` package directly from your app. However, if you want to build agentic AI applications with higher-level orchestration capabilities, you should use [Microsoft Agent Framework](/agent-framework/overview/agent-framework-overview). Agent Framework builds on the `Microsoft.Extensions.AI.Abstractions` package and provides concrete implementations of for different services, including OpenAI, Azure OpenAI, Azure AI Foundry, and more. + +This framework is the recommended approach for .NET apps that need to build agentic AI systems with advanced orchestration, multi-agent collaboration, and enterprise-grade security and observability. -If you just want to use the low-level services, such as and , you can reference the `Microsoft.Extensions.AI.Abstractions` package directly from your app. However, if you want to use higher-level, more opinionated approaches to AI, then you should use [Semantic Kernel](/semantic-kernel/overview/). +Agent Framework is a production-ready, open-source framework that brings together the best capabilities of Semantic Kernel and Microsoft Research's AutoGen. Agent Framework provides: -Semantic Kernel, which has a dependency on the `Microsoft.Extensions.AI.Abstractions` package, is an open-source library that enables AI integration and orchestration capabilities in your .NET apps. Its connectors provides concrete implementations of and for different services, including OpenAI, Amazon Bedrock, and Google Gemini. +- **Multi-agent orchestration**: Support for sequential, concurrent, group chat, handoff, and *magentic* (where a lead agent directs other agents) orchestration patterns. +- **Cloud and provider flexibility**: Cloud-agnostic (containers, on-premises, or multi-cloud) and provider-agnostic (for example, OpenAI or Azure AI Foundry) using plugin and connector models. +- **Enterprise-grade features**: Built-in observability (OpenTelemetry), Microsoft Entra security integration, and responsible AI features including prompt injection protection and task adherence monitoring. +- **Standards-based interoperability**: Integration with open standards like Agent-to-Agent (A2A) protocol and Model Context Protocol (MCP) for agent discovery and tool interaction. -The Semantic Kernel SDK is generally the recommended AI orchestration tool for .NET apps that use one or more AI services in combination with other APIs or web services, data stores, and custom code. Semantic Kernel benefits enterprise developers in the following ways: +For more information, see the [Microsoft Agent Framework documentation](/agent-framework/overview/agent-framework-overview). + +## Semantic Kernel for .NET -- Streamlines integration of AI capabilities into existing applications to enable a cohesive solution for enterprise products. -- Minimizes the learning curve of working with different AI models or services by providing abstractions that reduce complexity. -- Improves reliability by reducing the unpredictable behavior of prompts and responses from AI models. You can fine-tune prompts and plan tasks to create a controlled and predictable user experience. +[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. -For more information, see the [Semantic Kernel documentation](/semantic-kernel/overview/). +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 @@ -40,6 +47,7 @@ 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) | @@ -60,7 +68,7 @@ Azure offers many other AI services to build specific application capabilities a ## Develop with local AI models -.NET apps can also connect to local AI models for many different development scenarios. [Semantic Kernel](https://github.com/microsoft/semantic-kernel) is the recommended tool to connect to local models using .NET. Semantic Kernel can connect to many different models hosted across a variety of platforms and abstracts away lower-level implementation details. +.NET apps can also connect to local AI models for many different development scenarios. [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) is the recommended tool to connect to local models using .NET. This framework can connect to many different models hosted across a variety of platforms and abstracts away lower-level implementation details. For example, you can use [Ollama](https://ollama.com/) to [connect to local AI models with .NET](quickstarts/chat-local-model.md), including several small language models (SLMs) developed by Microsoft: @@ -78,6 +86,7 @@ For example, you can use [Ollama](https://ollama.com/) to [connect to local AI m ## Next steps +- [What is Microsoft Agent Framework?](/agent-framework/overview/agent-framework-overview) - [What is Semantic Kernel?](/semantic-kernel/overview/) - [Quickstart - Summarize text using Azure AI chat app with .NET](quickstarts/prompt-model.md) diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 3e23f0a436ee0..716b318b12440 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -141,7 +141,7 @@ | Functions extension for WebPubSub for SocketIO | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO_1.0.0-beta.4/sdk/webpubsub/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/) | | Provisioning - App Configuration | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_1.1.0/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | | Provisioning - App Containers | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.AppContainers/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppContainers-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppContainers_1.1.0/sdk/provisioning/Azure.Provisioning.AppContainers/) | -| Provisioning - App Service | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.2.0/sdk/provisioning/Azure.Provisioning.AppService/) | +| Provisioning - App Service | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.2.0)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.2.0/sdk/provisioning/Azure.Provisioning.AppService/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.3.0-beta.1/sdk/provisioning/Azure.Provisioning.AppService/) | | Provisioning - Application Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.ApplicationInsights-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_1.1.0/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | | Provisioning - Cognitive Services | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.1.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | | Provisioning - Communication | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.3/sdk/provisioning/Azure.Provisioning.Communication/) | @@ -210,7 +210,7 @@ | Resource Management - Container Apps | NuGet [1.5.0](https://www.nuget.org/packages/Azure.ResourceManager.AppContainers/1.5.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AppContainers-readme) | GitHub [1.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppContainers_1.5.0/sdk/containerapps/Azure.ResourceManager.AppContainers/) | | Resource Management - Container Instances | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerInstance/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerInstance-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerInstance_1.3.0/sdk/containerinstance/Azure.ResourceManager.ContainerInstance/) | | Resource Management - Container Orchestrator Runtime | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerOrchestratorRuntime/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerOrchestratorRuntime-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.ContainerOrchestratorRuntime_1.0.0-beta.1/sdk/containerorchestratorruntime/Azure.ResourceManager.ContainerOrchestratorRuntime/) | -| Resource Management - Container Registry | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.3.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerRegistry-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerRegistry_1.3.1/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry/) | +| Resource Management - Container Registry | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerRegistry-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerRegistry_1.4.0/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry/) | | Resource Management - Container Service | NuGet [1.2.5](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.2.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerService-readme) | GitHub [1.2.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.2.5/sdk/containerservice/Azure.ResourceManager.ContainerService/) | | Resource Management - Container Service Fleet | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerServiceFleet/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerServiceFleet/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerServiceFleet-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerServiceFleet_1.1.0/sdk/fleet/Azure.ResourceManager.ContainerServiceFleet/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerServiceFleet_1.2.0-beta.1/sdk/fleet/Azure.ResourceManager.ContainerServiceFleet/) | | Resource Management - Content Delivery Network | NuGet [1.5.0](https://www.nuget.org/packages/Azure.ResourceManager.Cdn/1.5.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Cdn-readme) | GitHub [1.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Cdn_1.5.0/sdk/cdn/Azure.ResourceManager.Cdn/) | @@ -416,6 +416,7 @@ | Speech Extension Telemetry | NuGet [1.46.0](https://www.nuget.org/packages/Microsoft.CognitiveServices.Speech.Extension.Telemetry/1.46.0) | | | | System Net Client Model | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/System.Net.ClientModel/1.0.0-beta.1) | | | | Unknown Display Name | NuGet [0.13.0](https://www.nuget.org/packages/Azure.Iot.Operations.Connector/0.13.0) | | | +| Unknown Display Name | NuGet [0.1.0](https://www.nuget.org/packages/Azure.Iot.Operations.Templates/0.1.0) | | | | Unknown Display Name | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp/1.0.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Mcp/2.0.0-beta.1) | | | | Unknown Display Name | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/1.0.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Mcp.linux-arm64/2.0.0-beta.1) | | | | Unknown Display Name | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Mcp.linux-x64/1.0.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Mcp.linux-x64/2.0.0-beta.1) | | | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 3c45a559e6eb5..68db1b766a7df 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -150,7 +150,7 @@ | Functions extension for WebPubSub for SocketIO | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO_1.0.0-beta.4/sdk/webpubsub/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/) | | Provisioning - App Configuration | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_1.1.0/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | | Provisioning - App Containers | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.AppContainers/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppContainers-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppContainers_1.1.0/sdk/provisioning/Azure.Provisioning.AppContainers/) | -| Provisioning - App Service | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.2.0/sdk/provisioning/Azure.Provisioning.AppService/) | +| Provisioning - App Service | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.2.0)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.2.0/sdk/provisioning/Azure.Provisioning.AppService/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.3.0-beta.1/sdk/provisioning/Azure.Provisioning.AppService/) | | Provisioning - Application Insights | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.ApplicationInsights-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_1.1.0/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | | Provisioning - Cognitive Services | NuGet [1.1.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.1.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | | Provisioning - Communication | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.3/sdk/provisioning/Azure.Provisioning.Communication/) | @@ -221,7 +221,7 @@ | Resource Management - Container Apps | NuGet [1.5.0](https://www.nuget.org/packages/Azure.ResourceManager.AppContainers/1.5.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AppContainers-readme) | GitHub [1.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AppContainers_1.5.0/sdk/containerapps/Azure.ResourceManager.AppContainers/) | | Resource Management - Container Instances | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerInstance/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerInstance-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerInstance_1.3.0/sdk/containerinstance/Azure.ResourceManager.ContainerInstance/) | | Resource Management - Container Orchestrator Runtime | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerOrchestratorRuntime/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerOrchestratorRuntime-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.ContainerOrchestratorRuntime_1.0.0-beta.1/sdk/containerorchestratorruntime/Azure.ResourceManager.ContainerOrchestratorRuntime/) | -| Resource Management - Container Registry | NuGet [1.3.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.3.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerRegistry-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerRegistry_1.3.1/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry/) | +| Resource Management - Container Registry | NuGet [1.4.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerRegistry/1.4.0) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerRegistry-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerRegistry_1.4.0/sdk/containerregistry/Azure.ResourceManager.ContainerRegistry/) | | Resource Management - Container Service | NuGet [1.2.5](https://www.nuget.org/packages/Azure.ResourceManager.ContainerService/1.2.5) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerService-readme) | GitHub [1.2.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerService_1.2.5/sdk/containerservice/Azure.ResourceManager.ContainerService/) | | Resource Management - Container Service Fleet | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.ContainerServiceFleet/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.ContainerServiceFleet/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.ContainerServiceFleet-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerServiceFleet_1.1.0/sdk/fleet/Azure.ResourceManager.ContainerServiceFleet/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.ContainerServiceFleet_1.2.0-beta.1/sdk/fleet/Azure.ResourceManager.ContainerServiceFleet/) | | Resource Management - Content Delivery Network | NuGet [1.5.0](https://www.nuget.org/packages/Azure.ResourceManager.Cdn/1.5.0) | [docs](/dotnet/api/overview/azure/ResourceManager.Cdn-readme) | GitHub [1.5.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Cdn_1.5.0/sdk/cdn/Azure.ResourceManager.Cdn/) | diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 6cba46b248d87..4960a56abbb54 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -61,6 +61,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | Title | Type of change | Introduced version | |-------|-------------------|--------------------| +| [CompositeMLDsa updated to draft-08](cryptography/10.0/composite-mldsa-draft-08.md) | Behavioral change | 10.0.0 | | [CoseSigner.Key can be null](cryptography/10.0/cosesigner-key-null.md) | Behavioral/source incompatible change | Preview 7 | | [MLDsa and SlhDsa 'SecretKey' members renamed](cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md) | Source incompatible | RC 1 | | [OpenSSL cryptographic primitives aren't supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 | @@ -117,8 +118,10 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [.NET CLI `--interactive` defaults to `true` in user scenarios](sdk/10.0/dotnet-cli-interactive.md) | Behavioral change | Preview 3 | | [`dotnet` CLI commands log non-command-relevant data to stderr](sdk/10.0/dotnet-cli-stderr-output.md) | Behavioral change | RC 2 | | [.NET tool packaging creates RuntimeIdentifier-specific tool packages](sdk/10.0/dotnet-tool-pack-publish.md) | Behavioral change | Preview 6 | +| [Code coverage EnableDynamicNativeInstrumentation defaults to false](sdk/10.0/code-coverage-dynamic-native-instrumentation.md) | Behavioral change | GA | | [Default workload configuration from 'loose manifests' to 'workload sets' mode](sdk/10.0/default-workload-config.md) | Behavioral change | Preview 2 | | [dnx.ps1 file is no longer included in .NET SDK](sdk/10.0/dnx-ps1-removed.md) | Source incompatible | GA | +| [Double quotes in file-level directives are disallowed](sdk/10.0/file-level-directive-double-quotes.md) | Source incompatible | GA | | [`dotnet new sln` defaults to SLNX file format](sdk/10.0/dotnet-new-sln-slnx-default.md) | Behavioral change | RC 1 | | [`dotnet package list` performs restore](sdk/10.0/dotnet-package-list-restore.md) | Behavioral change | Preview 4 | | [`dotnet restore` audits transitive packages](sdk/10.0/nugetaudit-transitive-packages.md) | Behavioral change | Preview 3 | diff --git a/docs/core/compatibility/cryptography/10.0/composite-mldsa-draft-08.md b/docs/core/compatibility/cryptography/10.0/composite-mldsa-draft-08.md new file mode 100644 index 0000000000000..62775430188b2 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/composite-mldsa-draft-08.md @@ -0,0 +1,45 @@ +--- +title: "Breaking change - CompositeMLDsa updated to draft-08" +description: "Learn about the breaking change in .NET 10 where CompositeMLDsa was updated from draft-07 to draft-08 of the Composite ML-DSA for use in X.509 Public Key Infrastructure specification." +ms.date: 11/04/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issue/48901 +--- + +# CompositeMLDsa updated to draft-08 + + has moved from draft-07 to draft-08 of the [Composite ML-DSA for use in X.509 Public Key Infrastructure](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) specification. The draft-08 format is not compatible with the draft-07 signatures, and key export/import formats are also incompatible across the draft-07/draft-08 boundary. draft-08 and draft-09 are compatible. + +## Version introduced + +.NET 10 GA + +## Previous behavior + +In preview and RC releases of .NET 10, signatures were generated and validated according to draft-07 of Composite ML-DSA for use in X.509 Public Key Infrastructure. + +Public key and private key export and import used the format from draft-07 of Composite ML-DSA for use in X.509 Public Key Infrastructure. + +## New behavior + +Starting in the .NET 10 GA release, signatures are generated and validated according to draft-08 of Composite ML-DSA for use in X.509 Public Key Infrastructure. + +Public key and private key export and import use the format from draft-08 of Composite ML-DSA for use in X.509 Public Key Infrastructure. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was made to stay current with the underlying specification. + +## Recommended action + +The class is marked as `[Experimental]`, partly because the specification isn't yet complete. Do not depend on this class in production. + +Discard any previously generated keys and signatures. + +## Affected APIs + +- diff --git a/docs/core/compatibility/sdk/10.0/code-coverage-dynamic-native-instrumentation.md b/docs/core/compatibility/sdk/10.0/code-coverage-dynamic-native-instrumentation.md new file mode 100644 index 0000000000000..42357703a88c5 --- /dev/null +++ b/docs/core/compatibility/sdk/10.0/code-coverage-dynamic-native-instrumentation.md @@ -0,0 +1,66 @@ +--- +title: "Breaking change - Code coverage EnableDynamicNativeInstrumentation defaults to false" +description: "Learn about the breaking change in .NET 10 where dynamic native instrumentation is disabled by default when collecting code coverage." +ms.date: 11/05/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/49376 +--- + +# Code coverage EnableDynamicNativeInstrumentation defaults to false + +Running `dotnet test --collect:"Code Coverage"` now disables dynamic native instrumentation by default. This change affects how code coverage is collected from native code. It doesn't affect how code coverage is collected from managed code. + +## Version introduced + +.NET 10 GA + +## Previous behavior + +Previously, dynamic native instrumentation was enabled by default and used a fallback for native modules when static native instrumentation couldn't be used. This behavior is described in [Static and dynamic native instrumentation](/visualstudio/test/customizing-code-coverage-analysis?view=vs-2022#static-and-dynamic-native-instrumentation). + +```bash +dotnet test --collect:"Code Coverage" +# Dynamic native instrumentation was enabled by default +``` + +## New behavior + +Starting in .NET 10, dynamic native instrumentation is disabled by default. The `false` option is set by default from `dotnet test` and `vstest`. If you explicitly set the option in a *runsettings* file, it isn't overridden. + +```bash +dotnet test --collect:"Code Coverage" +# Dynamic native instrumentation is now disabled by default +``` + +You can re-enable dynamic native instrumentation by setting `true` in your *runsettings* file. However, when you do so, it might fail with "The code execution cannot proceed because covrun64.dll was not found." This error can also happen for `covrun32.dll` in a 32-bit process. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Dynamic native instrumentation was enabled by default to maintain backwards compatibility in `dotnet test`. However, its way of injecting DLLs into the process isn't standard. With [security hardening changes](https://github.com/dotnet/runtime/pull/112359) in the .NET 10 runtime, it fails to find the linked DLL, causing the process to [crash with error](https://github.com/dotnet/sdk/issues/50950). The error might not be visible in non-interactive sessions or in the command line, but the process does crash. + +Dynamic native instrumentation is already disabled by default by `dotnet-coverage`, which is an alternative way to collect code coverage using the same underlying tools. It's also disabled by default for solutions in Visual Studio that don't have native projects. + +## Recommended action + +If you collect coverage on solutions that don't have any native components, you shouldn't be affected. However, you might observe increased performance when collecting coverage. + +If you collect coverage on solutions that include native components, such as C++ projects, you have the following options: + +- Configure your projects to use [static native instrumentation](/visualstudio/test/customizing-code-coverage-analysis#static-and-dynamic-native-instrumentation) + + OR + +- Update to Microsoft.CodeCoverage 18.0.1 and enable dynamic native instrumentation: + + - Add the setting `true` to your *runsettings* file. + - Globally opt out from this new default by setting the `VSTEST_DISABLE_DYNAMICNATIVE_CODECOVERAGE_DEFAULT_SETTING=1` environment variable. + + Similarly, when collecting code coverage with `vstest.console`, VSTest version 18.0.1 and newer is required to successfully collect dynamic native coverage on systems that have the .NET 10 SDK installed. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md b/docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md new file mode 100644 index 0000000000000..c6f820f3c167c --- /dev/null +++ b/docs/core/compatibility/sdk/10.0/file-level-directive-double-quotes.md @@ -0,0 +1,41 @@ +--- +title: "Breaking change - Double quotes in file-level directives are disallowed" +description: "Learn about the breaking change in .NET 10 where double quotes in file-level directives are disallowed." +ms.date: 11/04/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/48916 +--- + +# Double quotes in file-level directives are disallowed + +Usage of double quotes `"` inside `#:` file-level directives is now a build-time error when running file-based apps (for example, `dotnet run app.cs`). + +## Version introduced + +.NET 10 GA + +## Previous behavior + +In .NET 10 RC2 and older .NET 10 previews, quotes in directives weren't blocked but they didn't work as expected. They were only escaped as any other special character and passed to MSBuild. For example, `#:property Prop="my test"` resulted in `"my test"`. + +## New behavior + +An error is reported if a double quote `"` is encountered in any file-level directive. The error message is: + +> Directives currently cannot contain double quotes ("). + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +This change enables future support for quoted directives without introducing a breaking change. This also improves the error recovery experience if users try to use quotes now, thinking that's supported syntax. + +## Recommended action + +Don't use quotes in `#:` directives. If you really need to use a double quote (or another special character that currently isn't supported, like trailing whitespace), move the corresponding project metadata entry into a `Directory.Build.props` file instead (it will be picked up by the file-based app). Or, convert the file-based app to a full project via `dotnet project convert`. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index cdd46b00d6fe3..4394916aa0483 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -70,6 +70,8 @@ items: href: core-libraries/10.0/ymm-embedded-rounding.md - name: Cryptography items: + - name: CompositeMLDsa updated to draft-08 + href: cryptography/10.0/composite-mldsa-draft-08.md - name: CoseSigner.Key can be null href: cryptography/10.0/cosesigner-key-null.md - name: Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE @@ -126,6 +128,8 @@ items: href: reflection/10/makegeneric-signaturetype-validation.md - name: SDK and MSBuild items: + - name: Code coverage EnableDynamicNativeInstrumentation defaults to false + href: sdk/10.0/code-coverage-dynamic-native-instrumentation.md - name: .NET CLI `--interactive` defaults to `true` in user scenarios href: sdk/10.0/dotnet-cli-interactive.md - name: "`dotnet` CLI commands log non-command-relevant data to stderr" @@ -134,6 +138,8 @@ items: href: sdk/10.0/dotnet-tool-pack-publish.md - name: dnx.ps1 file is no longer included in .NET SDK href: sdk/10.0/dnx-ps1-removed.md + - name: Double quotes in file-level directives are disallowed + href: sdk/10.0/file-level-directive-double-quotes.md - name: "`dotnet restore` audits transitive packages" href: sdk/10.0/nugetaudit-transitive-packages.md - name: project.json not supported in `dotnet restore` diff --git a/docs/core/install/upgrade.md b/docs/core/install/upgrade.md index 8fa3fee613b96..c4159da908a94 100644 --- a/docs/core/install/upgrade.md +++ b/docs/core/install/upgrade.md @@ -1,7 +1,8 @@ --- title: Upgrade to a new .NET version -description: Learn how to upgrade an app to a new .NET version. Upgrade .NET when the current version goes out of support or when you want to use new features of .NET. -ms.date: 11/11/2024 +description: Learn how to upgrade an app to a new .NET version. Upgrade .NET when the current version goes out of support or when you want to use new features of .NET. Control versions of SDK, analyzers, and packages for predictable builds. +ms.date: 10/28/2025 +ai-usage: ai-assisted --- # Upgrade to a new .NET version @@ -51,6 +52,165 @@ More resources: - [Migrate an ASP.NET Core app](/aspnet/core/migration/) - [Upgrade .NET MAUI from .NET 7 to .NET 8](https://github.com/dotnet/maui/wiki/Upgrading-.NET-MAUI-from-.NET-7-to-.NET-8) +## Version pinning + +When you upgrade development tools like the .NET SDK, Visual Studio, or other components, you might encounter new behaviors, analyzer warnings, or breaking changes that affect your build process. By pinning to a version, you can upgrade your development environment while maintaining control over when specific components are updated in your projects. + +Version pinning provides several benefits: + +- **Predictable builds**: Ensures consistent build results across different machines and CI/CD environments. +- **Gradual adoption**: Allows you to adopt new features incrementally rather than all at once. +- **Avoid unexpected changes**: Prevents new analyzer rules, SDK behaviors, or package versions from causing build failures. +- **Team coordination**: Enables teams to upgrade together at a planned time rather than individually when tools update. +- **Debugging and troubleshooting**: Makes it easier to isolate issues when you control which versions changed. + +The following sections describe various mechanisms for controlling versions of different components in your .NET projects: + +- [Control SDK version with global.json](#control-sdk-version-with-globaljson) +- [Control analyzer behavior](#control-analyzer-behavior) +- [Control NuGet package versions](#control-nuget-package-versions) +- [Control MSBuild version](#control-msbuild-version) + +### Control SDK version with global.json + +You can pin the .NET SDK version for a project or solution by using a *global.json* file. This file specifies which SDK version to use when running .NET CLI commands and is independent of the runtime version your project targets. + +Create a *global.json* file in your solution root directory: + +```dotnetcli +dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature +``` + +This command creates the following *global.json* file that pins the SDK to version 9.0.100 or any later patch or feature band within the 9.0 major version: + +```json +{ + "sdk": { + "version": "9.0.100", + "rollForward": "latestFeature" + } +} +``` + +The `rollForward` policy controls how the SDK version is selected when the exact version isn't available. This configuration ensures that when you upgrade Visual Studio or install a new SDK, your project continues to use SDK 9.0.x until you explicitly update the *global.json* file. + +For more information, see [global.json overview](../tools/global-json.md). + +### Control analyzer behavior + +Code analyzers can introduce new warnings or change behavior between versions. You can control analyzer versions to maintain consistent builds by using the [`AnalysisLevel` property](../project-sdk/msbuild-props.md#analysislevel). This property allows you to lock to a specific version of analyzer rules, preventing new rules from being introduced when you upgrade the SDK. + +```xml + + 9.0 + +``` + +When set to `9.0`, only the analyzer rules that shipped with .NET 9 are enabled, even if you're using the .NET 10 SDK. This prevents new .NET 10 analyzer rules from affecting your build until you're ready to address them. + +For more information, see [AnalysisLevel](../project-sdk/msbuild-props.md#analysislevel). + +### Control NuGet package versions + +By managing package versions consistently across projects, you can prevent unexpected updates and maintain reliable builds. + +- [Package lock files](#package-lock-files) +- [Central package management](#central-package-management) +- [Package source mapping](#package-source-mapping) + +#### Package lock files + +Package lock files ensure that package restore operations use the exact same package versions across different environments. The lock file (`packages.lock.json`) records the exact versions of all packages and their dependencies. + +Enable lock files in your project file: + +```xml + + true + +``` + +To ensure builds fail if the lock file is out of date: + +```xml + + true + true + +``` + +After enabling lock files, run `dotnet restore` to generate the *packages.lock.json* file. Commit this file to source control. + +#### Central package management + +Central package management (CPM) allows you to manage package versions in a single location for all projects in a solution. This approach simplifies version management and ensures consistency across projects. + +Create a *Directory.Packages.props* file in your solution root: + +```xml + + + true + + + + + + + +``` + +In your project files, reference packages without specifying a version: + +```xml + + + + +``` + +#### Package source mapping + +Package source mapping allows you to control which NuGet feeds are used for specific packages, improving security and reliability. + +Configure source mapping in your *nuget.config* file: + +```xml + + + + + + + + + + + + + + + +``` + +This configuration ensures that all packages starting with `Contoso.` are only restored from the `contoso` feed, while other packages come from `nuget.org`. + +For more information, see [NuGet package restore](../tools/dotnet-restore.md). + +### Control MSBuild version + +Visual Studio supports side-by-side installation of multiple versions. For example, you can install Visual Studio 2026 and Visual Studio 2022 on the same machine. Each Visual Studio version includes a corresponding .NET SDK. When you update Visual Studio, the included SDK version is updated as well. However, you can continue using older SDK versions by installing them separately from the [.NET download page](https://dotnet.microsoft.com/download). + +MSBuild versions correspond to Visual Studio versions. For example, Visual Studio 2022 version 17.8 includes MSBuild 17.8. The .NET SDK also includes MSBuild. When you use `dotnet build`, you're using the MSBuild version included with the SDK specified by *global.json* or the latest installed SDK. + +To use a specific MSBuild version: + +- Use `dotnet build` with a pinned SDK version in *global.json*. +- Launch the appropriate Visual Studio Developer Command Prompt, which sets up the environment for that Visual Studio version's MSBuild. +- Directly invoke MSBuild from a specific Visual Studio installation (for example, `"C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe"`). + +For more information, see [.NET SDK, MSBuild, and Visual Studio versioning](../porting/versioning-sdk-msbuild-vs.md). + ## Update continuous integration (CI) CI pipelines follow a similar update process as project files and Dockerfiles. Typically, you can update [CI pipelines](https://github.com/actions/setup-dotnet) by changing only version values. @@ -68,3 +228,8 @@ FROM mcr.microsoft.com/dotnet/aspnet:9.0 ``` In a cloud service like [Azure App Service](/azure/app-service/quickstart-dotnetcore), a configuration change is needed. + +## See also + +- [Breaking changes in .NET 10](../compatibility/10.0.md) +- [Migrate an ASP.NET Core app](/aspnet/core/migration/) diff --git a/docs/core/porting/github-copilot-app-modernization/overview.md b/docs/core/porting/github-copilot-app-modernization/overview.md index 0d00dc928728d..0925aa5c4c1c7 100644 --- a/docs/core/porting/github-copilot-app-modernization/overview.md +++ b/docs/core/porting/github-copilot-app-modernization/overview.md @@ -27,15 +27,6 @@ With this assistant, you can: - Fix issues and apply best practices for cloud migration. - Validate that your app builds and tests successfully. -> [!IMPORTANT] -> Starting with Visual Studio 2022 17.14.16, the GitHub Copilot app modernization agent is included with Visual Studio. If you're using an older version of Visual Studio 2022, upgrade to the latest release. -> -> If you installed any of the following extensions published by Microsoft, uninstall them before using the version now included in Visual Studio: -> -> - .NET Upgrade Assistant -> - GitHub Copilot App Modernization – Upgrade for .NET -> - Azure Migrate Application and Code Assessment for .NET - ## Provide feedback Feedback is important to Microsoft and the efficiency of this agent. Use the [Suggest a feature](/visualstudio/ide/suggest-a-feature) and [Report a problem](/visualstudio/ide/report-a-problem) features of Visual Studio to provide feedback. diff --git a/docs/core/testing/mstest-analyzers/mstest0006.md b/docs/core/testing/mstest-analyzers/mstest0006.md index 9454fd1c7164d..b82dffc9b8d78 100644 --- a/docs/core/testing/mstest-analyzers/mstest0006.md +++ b/docs/core/testing/mstest-analyzers/mstest0006.md @@ -27,7 +27,7 @@ dev_langs: | **Introduced in version** | 3.2.0 | | **Is there a code fix** | Yes, starting with 3.7.0 | -> [NOTE] +> [!NOTE] > This analyzer is no longer relevant for MSTest 4 as the attribute was removed. ## Cause diff --git a/docs/core/testing/unit-testing-csharp-with-nunit.md b/docs/core/testing/unit-testing-csharp-with-nunit.md index 5f35fd312de4c..8e5e995eaf354 100644 --- a/docs/core/testing/unit-testing-csharp-with-nunit.md +++ b/docs/core/testing/unit-testing-csharp-with-nunit.md @@ -176,7 +176,7 @@ Instead of creating new tests, apply this attribute to create a single data-driv [!code-csharp[Sample_TestCode](~/samples/snippets/core/testing/unit-testing-using-nunit/csharp/PrimeService.Tests/PrimeService_IsPrimeShould.cs?name=Sample_TestCode)] -Run `dotnet test`, and two of these tests fail. To make all of the tests pass, change the `if` clause at the beginning of the `Main` method in the *PrimeService.cs* file: +Run `dotnet test`, and two of these tests fail. To make all of the tests pass, change the `if` clause at the beginning of the `IsPrime` method in the *PrimeService.cs* file: ```csharp if (candidate < 2) diff --git a/docs/core/whats-new/dotnet-10/libraries.md b/docs/core/whats-new/dotnet-10/libraries.md index 5c365d47c0719..a7959b652e3e3 100644 --- a/docs/core/whats-new/dotnet-10/libraries.md +++ b/docs/core/whats-new/dotnet-10/libraries.md @@ -156,7 +156,7 @@ private static bool VerifyWithExternalMu(MLDsa verifyingKey, ReadOnlySpan #### Composite ML-DSA -.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (currently at draft 7), including the and types, with implementation of the primitive methods for RSA variants. +.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (at draft 8 as of .NET 10 GA), including the and types, with implementation of the primitive methods for RSA variants. ```csharp var algorithm = CompositeMLDsaAlgorithm.MLDsa65WithRSA4096Pss; diff --git a/docs/csharp/fundamentals/types/index.md b/docs/csharp/fundamentals/types/index.md index 381a615c2adb3..209be162b385e 100644 --- a/docs/csharp/fundamentals/types/index.md +++ b/docs/csharp/fundamentals/types/index.md @@ -54,7 +54,7 @@ C# provides a standard set of built-in types. These represent integers, floating ## Custom types -You use the [`struct`](../../language-reference/builtin-types/struct.md), [`class`](../../language-reference/keywords/class.md), [`interface`](../../language-reference/keywords/interface.md), [`enum`](../../language-reference/builtin-types/enum.md), and [`record`](../../language-reference/builtin-types/record.md) constructs to create your own custom types. The .NET class library itself is a collection of custom types that you can use in your own applications. By default, the most frequently used types in the class library are available in any C# program. Others become available only when you explicitly add a project reference to the assembly that defines them. After the compiler has a reference to the assembly, you can declare variables (and constants) of the types declared in that assembly in source code. For more information, see [.NET Class Library](../../../standard/class-library-overview.md). +You use the [`struct`](../../language-reference/builtin-types/struct.md), [`class`](../../language-reference/keywords/class.md), [`interface`](../../language-reference/keywords/interface.md), [`enum`](../../language-reference/builtin-types/enum.md), and [`record`](../../language-reference/builtin-types/record.md) constructs to create your own custom types. The .NET class library itself is a collection of custom types that you can use in your own applications. By default, the most frequently used types in the class library are available in any C# program. Others become available only when you explicitly add a project reference to the assembly that defines them. After the compiler has a reference to the assembly, you can declare variables (and constants) of the types declared in that assembly in source code. One of the first decisions you make when defining a type is deciding which construct to use for your type. The following list helps make that initial decision. There's overlap in the choices. In most scenarios, more than one option is a reasonable choice. @@ -82,14 +82,14 @@ The following illustration shows the relationship between value types and refere Classes and structs are two of the basic constructs of the common type system in .NET. Each is essentially a data structure that encapsulates a set of data and behaviors that belong together as a logical unit. The data and behaviors are the *members* of the class, struct, or record. The members include its methods, properties, events, and so on, as listed later in this article. -A class, struct, or record declaration is like a blueprint that is used to create instances or objects at run time. If you define a class, struct, or record named `Person`, `Person` is the name of the type. If you declare and initialize a variable `p` of type `Person`, `p` is said to be an object or instance of `Person`. Multiple instances of the same `Person` type can be created, and each instance can have different values in its properties and fields. - +A class, struct, or record declaration is like a blueprint that is used to create instances or objects at run time. If you define a class, struct, or record named `Person`, `Person` is the name of the type. If you declare and initialize a variable `p` of type `Person`, `p` is said to be an object or instance of `Person`. Multiple instances of the same `Person` type can be created, and each instance can have different values in its properties and fields. + A class is a reference type. When an object of the type is created, the variable to which the object is assigned holds only a reference to that memory. When the object reference is assigned to a new variable, the new variable refers to the original object. Changes made through one variable are reflected in the other variable because they both refer to the same data. - + A struct is a value type. When a struct is created, the variable to which the struct is assigned holds the struct's actual data. When the struct is assigned to a new variable, it's copied. The new variable and the original variable therefore contain two separate copies of the same data. Changes made to one copy don't affect the other copy. Record types can be either reference types (`record class`) or value types (`record struct`). Record types contain methods that support value-equality. - + In general, classes are used to model more complex behavior. Classes typically store data that is intended to be modified after a class object is created. Structs are best suited for small data structures. Structs typically store data that isn't intended to be modified after the struct is created. Record types are data structures with extra compiler synthesized members. Records typically store data that isn't intended to be modified after the object is created. ### Value types diff --git a/docs/framework/data/adonet/dataset-datatable-dataview/datatables.md b/docs/framework/data/adonet/dataset-datatable-dataview/datatables.md index f80d993d90e3c..888d0ab29de35 100644 --- a/docs/framework/data/adonet/dataset-datatable-dataview/datatables.md +++ b/docs/framework/data/adonet/dataset-datatable-dataview/datatables.md @@ -6,53 +6,53 @@ ms.assetid: 52ff0e32-3e5a-41de-9a3b-7b04ea52b83e --- # DataTables -A is made up of a collection of tables, relationships, and constraints. In ADO.NET, objects are used to represent the tables in a **DataSet**. A **DataTable** represents one table of in-memory relational data; the data is local to the .NET-based application in which it resides, but can be populated from a data source such as Microsoft SQL Server using a **DataAdapter** For more information, see [Populating a DataSet from a DataAdapter](../populating-a-dataset-from-a-dataadapter.md). - - The **DataTable** class is a member of the **System.Data** namespace within the .NET Framework class library. You can create and use a **DataTable** independently or as a member of a **DataSet**, and **DataTable** objects can also be used in conjunction with other .NET Framework objects, including the . You access the collection of tables in a **DataSet** through the **Tables** property of the **DataSet** object. - - The schema, or structure of a table is represented by columns and constraints. You define the schema of a **DataTable** using objects as well as and objects. The columns in a table can map to columns in a data source, contain calculated values from expressions, automatically increment their values, or contain primary key values. - - In addition to a schema, a **DataTable** must also have rows to contain and order data. The class represents the actual data contained in a table. You use the **DataRow** and its properties and methods to retrieve, evaluate, and manipulate the data in a table. As you access and change the data within a row, the **DataRow** object maintains both its current and original state. - - You can create parent-child relationships between tables using one or more related columns in the tables. You create a relationship between **DataTable** objects using a . **DataRelation** objects can then be used to return the related child or parent rows of a particular row. For more information, see [Adding DataRelations](adding-datarelations.md). - -## In This Section - - [Creating a DataTable](creating-a-datatable.md) - Explains how to create a **DataTable** and add it to a **DataSet**. - - [DataTable Schema Definition](datatable-schema-definition.md) - Provides information about creating and using **DataColumn** objects and constraints. - - [Manipulating Data in a DataTable](manipulating-data-in-a-datatable.md) - Explains how to add, modify, and delete data in a table. Explains how to use **DataTable** events to examine changes to data in the table. - - [Handling DataTable Events](handling-datatable-events.md) - Provides information about the events available for use with a **DataTable**, including events when column values are modified and rows are added or deleted. - -## Related Sections - - [ADO.NET](../index.md) - Describes the ADO.NET architecture and components, and how to use them to access existing data sources and manage application data. - - [DataSets, DataTables, and DataViews](index.md) - Provides information about the ADO.NET **DataSet** including how to create relationships between tables. - - - Provides reference information about the **Constraint** object. - - - Provides reference information about the **DataColumn** object. - - - Provides reference information about the **DataSet** object. - - - Provides reference information about the **DataTable** object. - - [Class Library Overview](../../../../standard/class-library-overview.md) - Provides an overview of the .NET Framework class library, including the **System** namespace as well as its second-level namespace, **System.Data**. - +A is made up of a collection of tables, relationships, and constraints. In ADO.NET, objects are used to represent the tables in a **DataSet**. A **DataTable** represents one table of in-memory relational data; the data is local to the .NET-based application in which it resides, but can be populated from a data source such as Microsoft SQL Server using a **DataAdapter** For more information, see [Populating a DataSet from a DataAdapter](../populating-a-dataset-from-a-dataadapter.md). + + The **DataTable** class is a member of the **System.Data** namespace within the .NET Framework class library. You can create and use a **DataTable** independently or as a member of a **DataSet**, and **DataTable** objects can also be used in conjunction with other .NET Framework objects, including the . You access the collection of tables in a **DataSet** through the **Tables** property of the **DataSet** object. + + The schema, or structure of a table is represented by columns and constraints. You define the schema of a **DataTable** using objects as well as and objects. The columns in a table can map to columns in a data source, contain calculated values from expressions, automatically increment their values, or contain primary key values. + + In addition to a schema, a **DataTable** must also have rows to contain and order data. The class represents the actual data contained in a table. You use the **DataRow** and its properties and methods to retrieve, evaluate, and manipulate the data in a table. As you access and change the data within a row, the **DataRow** object maintains both its current and original state. + + You can create parent-child relationships between tables using one or more related columns in the tables. You create a relationship between **DataTable** objects using a . **DataRelation** objects can then be used to return the related child or parent rows of a particular row. For more information, see [Adding DataRelations](adding-datarelations.md). + +## In This Section + + [Creating a DataTable](creating-a-datatable.md) + Explains how to create a **DataTable** and add it to a **DataSet**. + + [DataTable Schema Definition](datatable-schema-definition.md) + Provides information about creating and using **DataColumn** objects and constraints. + + [Manipulating Data in a DataTable](manipulating-data-in-a-datatable.md) + Explains how to add, modify, and delete data in a table. Explains how to use **DataTable** events to examine changes to data in the table. + + [Handling DataTable Events](handling-datatable-events.md) + Provides information about the events available for use with a **DataTable**, including events when column values are modified and rows are added or deleted. + +## Related Sections + + [ADO.NET](../index.md)\ + Describes the ADO.NET architecture and components, and how to use them to access existing data sources and manage application data. + + [DataSets, DataTables, and DataViews](index.md)\ + Provides information about the ADO.NET including how to create relationships between tables. + + \ + Provides reference information about the **Constraint** object. + + \ + Provides reference information about the **DataColumn** object. + + \ + Provides reference information about the **DataSet** object. + + \ + Provides reference information about the **DataTable** object. + + [Core .NET libraries overview](../../../../standard/class-library-overview.md)\ + Provides an overview of the .NET class library. + ## See also - [ADO.NET Overview](../ado-net-overview.md) diff --git a/docs/framework/interop/blittable-and-non-blittable-types.md b/docs/framework/interop/blittable-and-non-blittable-types.md index ca2814a3c36ce..e9075328b0f1d 100644 --- a/docs/framework/interop/blittable-and-non-blittable-types.md +++ b/docs/framework/interop/blittable-and-non-blittable-types.md @@ -1,6 +1,6 @@ --- title: "Blittable and Non-Blittable Types" -description: Learn about blittable and non-blittable types. Blittable data types are commonly represented in managed and unmanaged memory and don't need special handling. +description: Learn about blittable and nonblittable types. Blittable data types are commonly represented in managed and unmanaged memory and don't need special handling. ms.date: "03/30/2017" helpviewer_keywords: - "interop marshalling, blittable types" @@ -9,62 +9,50 @@ ms.assetid: d03b050e-2916-49a0-99ba-f19316e5c1b3 --- # Blittable and Non-Blittable Types -Most data types have a common representation in both managed and unmanaged memory and do not require special handling by the interop marshaller. These types are called *blittable types* because they do not require conversion when they are passed between managed and unmanaged code. +Most data types have a common representation in both managed and unmanaged memory and don't require special handling by the interop marshaller. These types are called *blittable types* because they don't require conversion when they're passed between managed and unmanaged code. - Structures that are returned from platform invoke calls must be blittable types. Platform invoke does not support non-blittable structures as return types. + Structures that are returned from platform invoke calls must be blittable types. Platform invoke doesn't support nonblittable structures as return types. The following types from the namespace are blittable types: - - - - - - - - - - - - - - - - - - - - - - - The following complex types are also blittable types: - One-dimensional arrays of blittable primitive types, such as an array of integers. However, a type that contains a variable array of blittable types is not itself blittable. +- Formatted value types that contain only blittable types (and classes if they're marshalled as formatted types). For more information about formatted value types, see [Default marshalling for value types](default-marshalling-behavior.md#default-marshalling-for-value-types). -- Formatted value types that contain only blittable types (and classes if they are marshalled as formatted types). For more information about formatted value types, see [Default marshalling for value types](default-marshalling-behavior.md#default-marshalling-for-value-types). - - Object references are not blittable. This includes an array of references to objects that are blittable by themselves. For example, you can define a structure that is blittable, but you cannot define a blittable type that contains an array of references to those structures. + Object references aren't blittable. In addition, an array of references to objects that are blittable by themselves isn't blittable. For example, you can define a structure that's blittable, but you can't define a blittable type that contains an array of references to those structures. As an optimization, arrays of blittable primitive types and classes that contain only blittable members are [pinned](copying-and-pinning.md) instead of copied during marshalling. These types can appear to be marshalled as In/Out parameters when the caller and callee are in the same apartment. However, these types are actually marshalled as In parameters, and you must apply the and attributes if you want to marshal the argument as an In/Out parameter. - Some managed data types require a different representation in an unmanaged environment. These non-blittable data types must be converted into a form that can be marshalled. For example, managed strings are non-blittable types because they must be converted into string objects before they can be marshalled. + Some managed data types require a different representation in an unmanaged environment. These nonblittable data types must be converted into a form that can be marshalled. For example, managed strings are nonblittable types because they must be converted into string objects before they can be marshalled. - The following table lists non-blittable types from the namespace. [Delegates](default-marshalling-behavior.md#default-marshalling-for-delegates), which are data structures that refer to a static method or to a class instance, are also non-blittable. + The following table lists nonblittable types from the namespace. [Delegates](default-marshalling-behavior.md#default-marshalling-for-delegates), which are data structures that refer to a static method or to a class instance, are also nonblittable. -| Non-blittable type | Description | +| Nonblittable type | Description | |---------------------------------------------------|-----------------------------------------------| -|[System.Array](default-marshalling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| -|[System.Boolean](/previous-versions/dotnet/netframework-4.0/t2t3725f(v=vs.100))|Converts to a 1, 2, or 4-byte value with `true` as 1 or -1.| -|[System.Char](/previous-versions/dotnet/netframework-4.0/6tyybbf2(v=vs.100))|Converts to a Unicode or ANSI character.| -|[System.Class](/previous-versions/dotnet/netframework-4.0/s0968xy8(v=vs.100))|Converts to a class interface.| -|[System.Object](default-marshalling-for-objects.md)|Converts to a variant or an interface.| -|[System.String](default-marshalling-for-strings.md)|Converts to a string terminating in a null reference or to a BSTR.| -|[System.ValueType](/previous-versions/dotnet/netframework-4.0/0t2cwe11(v=vs.100))|Converts to a structure with a fixed memory layout.| -|[T[]](default-marshalling-for-arrays.md)|Converts to a C-style array or a `SAFEARRAY`.| - -Class and object types are supported only by COM interop. For corresponding types in Visual Basic, C#, and C++, see the [Class Library Overview](../../standard/class-library-overview.md). +| [System.Array](default-marshalling-for-arrays.md) | Converts to a C-style array or a `SAFEARRAY`. | +| [System.Boolean](/previous-versions/dotnet/netframework-4.0/t2t3725f(v=vs.100)) | Converts to a 1, 2, or 4-byte value with `true` as 1 or -1. | +| [System.Char](/previous-versions/dotnet/netframework-4.0/6tyybbf2(v=vs.100)) | Converts to a Unicode or ANSI character. | +| [System.Class](/previous-versions/dotnet/netframework-4.0/s0968xy8(v=vs.100)) | Converts to a class interface. | +| [System.Object](default-marshalling-for-objects.md) | Converts to a variant or an interface. | +| [System.String](default-marshalling-for-strings.md) | Converts to a string terminating in a null reference or to a BSTR. | +| [System.ValueType](/previous-versions/dotnet/netframework-4.0/0t2cwe11(v=vs.100)) | Converts to a structure with a fixed memory layout. | +| [T[]](default-marshalling-for-arrays.md) | Converts to a C-style array or a `SAFEARRAY`. | + +Class and object types are supported only by COM interop. ## See also diff --git a/docs/fundamentals/code-analysis/configuration-options.md b/docs/fundamentals/code-analysis/configuration-options.md index 031c5a9a712f1..662aac41be0bd 100644 --- a/docs/fundamentals/code-analysis/configuration-options.md +++ b/docs/fundamentals/code-analysis/configuration-options.md @@ -78,14 +78,14 @@ Rule-specific options can be applied to a single rule, a set of rules, or all ru The following table shows the different rule severities that you can configure for all analyzer rules, including [code quality](quality-rules/index.md) and [code style](style-rules/index.md) rules. -| Severity configuration value | Build-time behavior | -|-|-| -| `error` | Violations appear as build *errors* and cause builds to fail.| -| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). | -| `suggestion` | Violations appear as build *messages* and as suggestions in the Visual Studio IDE. (In Visual Studio, suggestions appear as three gray dots under the first two characters.) | -| `silent` | Violations aren't visible to the user.

However, for code-style rules, Visual Studio code-generation features still generate code in this style. These rules also participate in cleanup and appear in the **Quick Actions and Refactorings** menu in Visual Studio. | -| `none` | Rule is suppressed completely.

However, for code-style rules, Visual Studio code-generation features still generate code in this style. | -| `default` | The default severity of the rule is used. The default severities for each .NET release are listed in the [roslyn-analyzers repo](https://github.com/dotnet/roslyn-analyzers/blob/main/src/NetAnalyzers/Core/AnalyzerReleases.Shipped.md). In that table, "Disabled" corresponds to `none`, "Hidden" corresponds to `silent`, and "Info" corresponds to `suggestion`. | +| Severity configuration value | Build-time behavior | +|------------------------------|---------------------------------------------------------------| +| `error` | Violations appear as build *errors* and cause builds to fail. | +| `warning` | Violations appear as build *warnings* but do not cause builds to fail (unless you have an option set to treat warnings as errors). | +| `suggestion` | Violations appear as build *messages* and as suggestions in the Visual Studio IDE. (In Visual Studio, suggestions appear as three gray dots under the first two characters.) | +| `silent` | Violations aren't visible to the user.

However, for code-style rules, Visual Studio code-generation features still generate code in this style. These rules also participate in cleanup and appear in the **Quick Actions and Refactorings** menu in Visual Studio. | +| `none` | Rule is suppressed completely.

However, for code-style rules, Visual Studio code-generation features still generate code in this style. | +| `default` | The default severity of the rule is used. The default severities for each .NET release are listed in the [roslyn-analyzers repo](https://github.com/dotnet/roslyn-analyzers/blob/main/src/NetAnalyzers/Core/AnalyzerReleases.Shipped.md). In that table, "Disabled" corresponds to `none`, "Hidden" corresponds to `silent`, and "Info" corresponds to `suggestion`. | #### Scope diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1877.md b/docs/fundamentals/code-analysis/quality-rules/ca1877.md new file mode 100644 index 0000000000000..c0e3fb7961a73 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/ca1877.md @@ -0,0 +1,80 @@ +--- +title: "CA1877: Use 'Path.Combine' or 'Path.Join' overloads (code analysis)" +description: "Learn about code analysis rule CA1877: Use 'Path.Combine' or 'Path.Join' overloads" +ms.date: 11/05/2025 +ms.topic: reference +f1_keywords: + - CA1877 + - UsePathCombineOrPathJoinAnalyzer +helpviewer_keywords: + - CA1877 +dev_langs: + - CSharp + - VB +ai-usage: ai-generated +--- + +# CA1877: Use 'Path.Combine' or 'Path.Join' overloads + +| Property | Value | +|-------------------------------------|----------------------------------------| +| **Rule ID** | CA1877 | +| **Title** | Use `Path.Combine` or `Path.Join` overloads | +| **Category** | [Performance](performance-warnings.md) | +| **Fix is breaking or non-breaking** | Non-breaking | +| **Enabled by default in .NET 10** | As suggestion | + +## Cause + +Multiple consecutive or operations are used to build a path. + +## Rule description + +When you use multiple consecutive `Path.Combine` or `Path.Join` operations, it's more efficient to use an overload that accepts multiple path segments. This approach reduces the number of allocations and function calls, improving performance. Both methods provide overloads that accept multiple parameters, allowing you to collapse consecutive operations into a single call. + +## How to fix violations + +Replace consecutive `Path.Combine` or `Path.Join` operations with a single call using an overload that accepts all path segments. + +A *code fix* that automatically performs this transformation is available. + +## Example + +The following code snippet shows a violation of CA1877: + +:::code language="csharp" source="./snippets/csharp/all-rules/CA1877.cs" id="Violation"::: +:::code language="vb" source="./snippets/vb/all-rules/CA1877.vb" id="Violation"::: + +The following code snippet fixes the violation: + +:::code language="csharp" source="./snippets/csharp/all-rules/CA1877.cs" id="Fix"::: +:::code language="vb" source="./snippets/vb/all-rules/CA1877.vb" id="Fix"::: + +## When to suppress warnings + +It's safe to suppress a warning from this rule if performance isn't a concern. + +## Suppress a warning + +If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule. + +```csharp +#pragma warning disable CA1877 +// The code that's violating the rule is on this line. +#pragma warning restore CA1877 +``` + +To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md). + +```ini +[*.{cs,vb}] +dotnet_diagnostic.CA1877.severity = none +``` + +For more information, see [How to suppress code analysis warnings](../suppress-warnings.md). + +## See also + +- [Performance rules](performance-warnings.md) +- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/ca2026.md b/docs/fundamentals/code-analysis/quality-rules/ca2026.md new file mode 100644 index 0000000000000..99e2c74659bab --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/ca2026.md @@ -0,0 +1,77 @@ +--- +title: "CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement" +description: "Learn about code analysis rule CA2026 - Prefer JsonElement.Parse over JsonDocument.Parse().RootElement" +ms.date: 11/05/2025 +f1_keywords: + - CA2026 + - PreferJsonElementParseOverJsonDocumentParse +helpviewer_keywords: + - CA2026 +ai-usage: ai-assisted +dev_langs: +- CSharp +- VB +--- + +# CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement + +| Property | Value | +|-------------------------------------|--------------------------------------------------------------------------| +| **Rule ID** | CA2026 | +| **Title** | Prefer `JsonElement.Parse` over `JsonDocument.Parse().RootElement` | +| **Category** | [Reliability](reliability-warnings.md) | +| **Fix is breaking or non-breaking** | Non-breaking | +| **Enabled by default in .NET 10** | As suggestion | + +## Cause + +Code uses `JsonDocument.Parse().RootElement` to parse JSON into a . + +## Rule description + + is more efficient than calling `JsonDocument.Parse().RootElement`. The type implements and rents arrays from the , which can lead to memory leaks or increased GC pressure if you don't properly dispose the document. The `JsonElement.Parse` method, introduced in .NET 10, parses JSON directly into a without these concerns, making it more efficient and less error-prone. + +## How to fix violations + +Replace calls to `JsonDocument.Parse().RootElement` with `JsonElement.Parse()`. + +## Examples + +The following code snippet shows a violation of CA2026: + +:::code language="csharp" source="snippets/csharp/all-rules/ca2026.cs" id="Violation"::: +:::code language="vb" source="snippets/vb/all-rules/ca2026.vb" id="Violation"::: + +The following code snippet fixes the violation: + +:::code language="csharp" source="snippets/csharp/all-rules/ca2026.cs" id="Fixed"::: +:::code language="vb" source="snippets/vb/all-rules/ca2026.vb" id="Fixed"::: + +## When to suppress warnings + +Don't suppress warnings from this rule. If you're targeting .NET 10 or later, you should use `JsonElement.Parse()` for better performance and resource management. + +## Suppress a warning + +If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule. + +```csharp +#pragma warning disable CA2026 +// The code that's violating the rule is on this line. +#pragma warning restore CA2026 +``` + +To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md). + +```ini +[*.{cs,vb}] +dotnet_diagnostic.CA2026.severity = none +``` + +For more information, see [How to suppress code analysis warnings](../suppress-warnings.md). + +## See also + +- [Reliability rules](reliability-warnings.md) +- +- diff --git a/docs/fundamentals/code-analysis/quality-rules/index.md b/docs/fundamentals/code-analysis/quality-rules/index.md index 720c1eb06c983..f501ebaaa1e34 100644 --- a/docs/fundamentals/code-analysis/quality-rules/index.md +++ b/docs/fundamentals/code-analysis/quality-rules/index.md @@ -176,6 +176,7 @@ The following table lists code quality analysis rules. > | [CA1873: Avoid potentially expensive logging](ca1873.md) | In many situations, logging is disabled or set to a log level that results in an unnecessary evaluation for logging arguments. | > | [CA1874: Use `Regex.IsMatch`](ca1874.md) | `Regex.IsMatch` is simpler and faster than `Regex.Match(...).Success`. | > | [CA1875: Use `Regex.Count`](ca1875.md) | `Regex.Count` is simpler and faster than `Regex.Matches(...).Count`. | +> | [CA1877: Use 'Path.Combine' or 'Path.Join' overloads](ca1877.md) | When multiple `Path.Combine` or `Path.Join` operations are nested, they can be collapsed into a single operation for better performance and readability. | > | [CA2000: Dispose objects before losing scope](ca2000.md) | Because an exceptional event might occur that will prevent the finalizer of an object from running, the object should be explicitly disposed before all references to it are out of scope. | > | [CA2002: Do not lock on objects with weak identity](ca2002.md) |An object is said to have a weak identity when it can be directly accessed across application domain boundaries. A thread that tries to acquire a lock on an object that has a weak identity can be blocked by a second thread in a different application domain that has a lock on the same object. | > | [CA2007: Do not directly await a Task](ca2007.md) | An asynchronous method [awaits](../../../csharp/language-reference/operators/await.md) a directly. When an asynchronous method awaits a directly, continuation occurs in the same thread that created the task. This behavior can be costly in terms of performance and can result in a deadlock on the UI thread. Consider calling to signal your intention for continuation. | @@ -196,6 +197,7 @@ The following table lists code quality analysis rules. > | [CA2023: Invalid braces in message template](ca2023.md) | The braces present in the message template are invalid. Ensure any braces in the message template are valid opening/closing braces, or are escaped. | > | [CA2024: Do not use StreamReader.EndOfStream in async methods](ca2024.md) | The property can cause unintended synchronous blocking when no data is buffered. Instead, use directly, which returns `null` when reaching the end of the stream. | > | [CA2025: Do not pass `IDisposable` instances into unawaited tasks](ca2025.md) | Unawaited tasks that use `IDisposable` instances might use those instances long after they have been disposed. Ensure tasks using those instances are completed before the instances are disposed. | +> | [CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement](ca2026.md) | It's more efficient to call `JsonElement.Parse` directly than to call `JsonDocument.Parse().RootElement`. | > | [CA2100: Review SQL queries for security vulnerabilities](ca2100.md) | A method sets the System.Data.IDbCommand.CommandText property by using a string that is built from a string argument to the method. This rule assumes that the string argument contains user input. A SQL command string that is built from user input is vulnerable to SQL injection attacks. | > | [CA2101: Specify marshalling for P/Invoke string arguments](ca2101.md) | A platform invoke member allows partially trusted callers, has a string parameter, and does not explicitly marshal the string. This can cause a potential security vulnerability. | > | [CA2109: Review visible event handlers](ca2109.md) | A public or protected event-handling method was detected. Event-handling methods should not be exposed unless absolutely necessary. | diff --git a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md index d46d9b9608e87..0e88fd280368f 100644 --- a/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/performance-warnings.md @@ -83,3 +83,4 @@ Performance rules support high-performance libraries and applications. | [CA1873: Avoid potentially expensive logging](ca1873.md) | When logging methods are called, their arguments are evaluated regardless of whether the logging level is enabled. This can result in expensive operations being executed even when the log message won't be written. For better performance, guard expensive logging calls with a check to or use the `LoggerMessage` pattern. | | [CA1874: Use 'Regex.IsMatch'](ca1874.md) | is simpler and faster than `Regex.Match(...).Success`. | | [CA1875: Use 'Regex.Count'](ca1875.md) | is simpler and faster than `Regex.Matches(...).Count`. | +| [CA1877: Use 'Path.Combine' or 'Path.Join' overloads](ca1877.md) | Multiple consecutive or operations can be collapsed into a single call using overloads that accept multiple path segments. | diff --git a/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md b/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md index 6437efebefa8a..41120f7ae0107 100644 --- a/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md +++ b/docs/fundamentals/code-analysis/quality-rules/reliability-warnings.md @@ -35,3 +35,4 @@ Reliability rules support library and application reliability, such as correct m | [CA2023: Invalid braces in message template](ca2023.md) | Logging message templates use curly braces `{` and `}` to denote named placeholders for values. Invalid brace usage in message templates can result in runtime exceptions or unexpected logging behavior. | | [CA2024: Do not use StreamReader.EndOfStream in async methods](ca2024.md) | The property can cause unintended synchronous blocking when no data is buffered. Instead, use directly, which returns `null` when reaching the end of the stream. | | [CA2025: Do not pass `IDisposable` instances into unawaited tasks](ca2025.md) | Unawaited tasks that use `IDisposable` instances might use those instances long after they have been disposed. Ensure tasks using those instances are completed before the instances are disposed. | +| [CA2026: Prefer JsonElement.Parse over JsonDocument.Parse().RootElement](ca2026.md) | It's more efficient to call directly than to call `JsonDocument.Parse().RootElement`. | diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/all-rules.csproj b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/all-rules.csproj index b286c3c5c450a..d73c66d23f908 100644 --- a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/all-rules.csproj +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/all-rules.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net10.0 enable all_rules diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1877.cs b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1877.cs new file mode 100644 index 0000000000000..f9de62f20db4d --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1877.cs @@ -0,0 +1,36 @@ +using System.IO; + +class ViolationExample +{ + // + public string GetFilePath(string folder, string subfolder, string filename) + { + // Violation. + string temp = Path.Combine(folder, subfolder); + return Path.Combine(temp, filename); + } + + public string GetLogPath(string baseDir, string date, string category) + { + // Violation. + return Path.Join(Path.Join(baseDir, date), category); + } + // +} + +class FixExample +{ + // + public string GetFilePath(string folder, string subfolder, string filename) + { + // No violation. + return Path.Combine(folder, subfolder, filename); + } + + public string GetLogPath(string baseDir, string date, string category) + { + // No violation. + return Path.Join(baseDir, date, category); + } + // +} diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2026.cs b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2026.cs new file mode 100644 index 0000000000000..3284ccf49ffa3 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca2026.cs @@ -0,0 +1,23 @@ +using System.Text.Json; + +namespace ca2026 +{ + public static class Examples + { + // + public static void ProcessJsonViolation(string json) + { + JsonElement element = JsonDocument.Parse(json).RootElement; + //... + } + // + + // + public static void ProcessJsonFixed(string json) + { + JsonElement element = JsonElement.Parse(json); + //... + } + // + } +} diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj index a651c1e18355e..d8d4f77b12ce8 100644 --- a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj @@ -3,7 +3,7 @@ Exe all_rules - net9.0 + net10.0 $(NoWarn);SYSLIB0050 diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1877.vb b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1877.vb new file mode 100644 index 0000000000000..4a5f3b2a90751 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1877.vb @@ -0,0 +1,31 @@ +Imports System.IO + +Class ViolationExample + ' + Public Function GetFilePath(folder As String, subfolder As String, filename As String) As String + ' Violation. + Dim temp As String = Path.Combine(folder, subfolder) + Return Path.Combine(temp, filename) + End Function + + Public Function GetLogPath(baseDir As String, [date] As String, category As String) As String + ' Violation. + Return Path.Join(Path.Join(baseDir, [date]), category) + End Function + ' +End Class + +Class FixExample + ' + Public Function GetFilePath(folder As String, subfolder As String, filename As String) As String + ' No violation. + Return Path.Combine(folder, subfolder, filename) + End Function + + Public Function GetLogPath(baseDir As String, [date] As String, category As String) As String + ' No violation. + Return Path.Join(baseDir, [date], category) + End Function + ' +End Class + diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2026.vb b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2026.vb new file mode 100644 index 0000000000000..e6a51972dd137 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2026.vb @@ -0,0 +1,23 @@ +Imports System.Text.Json + +Namespace ca2026 + + Public Module Examples + + ' + Public Sub ProcessJsonViolation(json As String) + Dim element As JsonElement = JsonDocument.Parse(json).RootElement + '... + End Sub + ' + + ' + Public Sub ProcessJsonFixed(json As String) + Dim element As JsonElement = JsonElement.Parse(json) + '... + End Sub + ' + + End Module + +End Namespace diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 7b74f1965d772..5f6cb1b04327a 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -255,7 +255,7 @@ items: href: runtime-libraries/system-convert.md - name: Choose between anonymous and tuple types href: ../standard/base-types/choosing-between-anonymous-and-tuple.md - - name: Class library overview + - name: Core .NET libraries overview href: ../standard/class-library-overview.md - name: Supplemental API remarks items: diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 629a2c1d8e076..302c82cd9adda 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -3287,6 +3287,8 @@ items: href: ../../fundamentals/code-analysis/quality-rules/ca1874.md - name: CA1875 href: ../../fundamentals/code-analysis/quality-rules/ca1875.md + - name: CA1877 + href: ../../fundamentals/code-analysis/quality-rules/ca1877.md - name: SingleFile rules items: - name: Overview @@ -3347,6 +3349,8 @@ items: href: ../../fundamentals/code-analysis/quality-rules/ca2024.md - name: CA2025 href: ../../fundamentals/code-analysis/quality-rules/ca2025.md + - name: CA2026 + href: ../../fundamentals/code-analysis/quality-rules/ca2026.md - name: Security rules items: - name: Overview diff --git a/docs/standard/class-library-overview.md b/docs/standard/class-library-overview.md index e00538be31682..9e34f12f75029 100644 --- a/docs/standard/class-library-overview.md +++ b/docs/standard/class-library-overview.md @@ -1,42 +1,9 @@ --- -title: .NET class library overview -description: Learn about the .NET class library. .NET APIs include classes, interfaces, delegates, and value types to provide access to system functionality. -ms.date: 04/22/2021 -helpviewer_keywords: - - "classes [.NET], library overview" - - ".NET, library overview" - - "class objects value type" - - "naming conventions [.NET]" - - "types, .NET" - - "user-defined types" - - "Visual Basic, data types" - - "data types [.NET], C++" - - "Visual C#, data types" - - "libraries, .NET" - - "data types [.NET], F#" - - "System namespace" - - "F#, data types" - - ".NET, class library" - - "type system [.NET]" - - "data types [.NET]" - - "value types" - - "data types [.NET], Visual Basic" - - "Common Language Specification" - - "namespaces [.NET]" - - "floating point value type" - - "class library [.NET]" - - "CLS" - - "logical value type" - - "built-in types" - - "namespaces [.NET], about namespaces" - - "Visual C++, data types" - - "members [.NET], type" - - "data types [.NET], C#" - - "integer value type" - - "base types, class library" -ms.assetid: 7e4c5921-955d-4b06-8709-101873acf157 +title: Overview of core .NET libraries +description: Learn about the core .NET libraries. .NET APIs include classes, interfaces, delegates, and value types to provide access to system functionality. +ms.date: 11/05/2025 --- -# .NET class library overview +# Core .NET libraries overview .NET APIs include classes, interfaces, delegates, and value types that expedite and optimize the development process and provide access to system functionality. To facilitate interoperability between languages, most .NET types are CLS-compliant and can therefore be used from any programming language whose compiler conforms to the common language specification (CLS). @@ -49,79 +16,58 @@ ms.assetid: 7e4c5921-955d-4b06-8709-101873acf157 - Invoke .NET security checks. - Provide data access, rich client-side GUI, and server-controlled, client-side GUI. -.NET provides a rich set of interfaces, as well as abstract and concrete (non-abstract) classes. You can use the concrete classes as-is or, in many cases, derive your own classes from them. To use the functionality of an interface, you can either create a class that implements the interface or derive a class from one of the .NET classes that implements the interface. +.NET provides a rich set of interfaces as well as abstract and concrete (non-abstract) classes. You can use the concrete classes as-is or, in many cases, derive your own classes from them. To use the functionality of an interface, you can either create a class that implements the interface or derive a class from one of the .NET classes that implements the interface. ## Naming conventions - .NET types use a dot syntax naming scheme that connotes a hierarchy. This technique groups related types into namespaces so they can be searched and referenced more easily. The first part of the full name—up to the rightmost dot—is the namespace name. The last part of the name is the type name. For example, `System.Collections.Generic.List` represents the `List` type, which belongs to the `System.Collections.Generic` namespace. The types in can be used to work with generic collections. + .NET types use a dot syntax naming scheme to represent a hierarchy. Related types are grouped into namespaces so they can be searched and referenced more easily. The first part of the full name is the namespace name. The last part of the name is the type or member name. For example, `System.Collections.Generic.List` represents the type, which belongs to the `System.Collections.Generic` namespace. The types in can be used to work with generic collections. - This naming scheme makes it easy for library developers extending .NET to create hierarchical groups of types and name them in a consistent, informative manner. It also allows types to be unambiguously identified by their full name (that is, by their namespace and type name), which prevents type name collisions. Library developers are expected to use the following convention when creating names for their namespaces: - - *CompanyName*.*TechnologyName* - - For example, the namespace `Microsoft.Word` conforms to this guideline. + This naming scheme makes it easy for library developers who extend .NET to create hierarchical groups of types and name them in a consistent, informative manner. It also allows types to be unambiguously identified by their full name (that is, by their namespace and type name), which prevents type name collisions. The use of naming patterns to group related types into namespaces is a useful way to build and document class libraries. However, this naming scheme has no effect on visibility, member access, inheritance, security, or binding. A namespace can be partitioned across multiple assemblies and a single assembly can contain types from multiple namespaces. The assembly provides the formal structure for versioning, deployment, security, loading, and visibility in the common language runtime. - For more information on namespaces and type names, see [Common Type System](base-types/common-type-system.md). + For more information on namespaces and type names, see [Common type system](base-types/common-type-system.md). ## System namespace - The namespace is the root namespace for fundamental types in .NET. This namespace includes classes that represent the base data types used by all applications, for example, (the root of the inheritance hierarchy), , , , , and . Many of these types correspond to the primitive data types that your programming language uses. When you write code using .NET types, you can use your language's corresponding keyword when a .NET base data type is expected. - - The following table lists the base types that .NET supplies, briefly describes each type, and indicates the corresponding type in Visual Basic, C#, C++, and F#. - -|Category|Class name|Description|Visual Basic data type|C# data type|C++/CLI data type|F# data type| -|--------------|----------------|-----------------|----------------------------|-------------------|---------------------|-----------------------| -|Integer||An 8-bit unsigned integer.|`Byte`|`byte`|`unsigned char`|`byte`| -|||An 8-bit signed integer.

Not CLS-compliant.|`SByte`|`sbyte`|`char` or `signed char`|`sbyte`| -|||A 16-bit signed integer.|`Short`|`short`|`short`|`int16`| -|||A 32-bit signed integer.|`Integer`|`int`|`int` or `long`|`int`| -|||A 64-bit signed integer.|`Long`|`long`|`__int64`|`int64`| -|||A 16-bit unsigned integer.

Not CLS-compliant.|`UShort`|`ushort`|`unsigned short`|`uint16`| -|||A 32-bit unsigned integer.

Not CLS-compliant.|`UInteger`|`uint`|`unsigned int` or `unsigned long`|`uint32`| -|||A 64-bit unsigned integer.

Not CLS-compliant.|`ULong`|`ulong`|`unsigned __int64`|`uint64`| -|Floating point||A half-precision (16-bit) floating-point number.||||| -|||A single-precision (32-bit) floating-point number.|`Single`|`float`|`float`|`float32` or `single`| -|||A double-precision (64-bit) floating-point number.|`Double`|`double`|`double`|`float` or `double`| -|Logical||A Boolean value (true or false).|`Boolean`|`bool`|`bool`|`bool`| -|Other||A Unicode (16-bit) character.|`Char`|`char`|`wchar_t`|`char`| -|||A decimal (128-bit) value.|`Decimal`|`decimal`|`Decimal`|`decimal`| -|||A signed integer whose size depends on the underlying platform (a 32-bit value on a 32-bit platform and a 64-bit value on a 64-bit platform).| |`nint`| |`unativeint`| -|||An unsigned integer whose size depends on the underlying platform (a 32- bit value on a 32-bit platform and a 64-bit value on a 64-bit platform).

Not CLS-compliant.| |`nuint`| |`unativeint`| -|||The root of the object hierarchy.|`Object`|`object`|`Object^`|`obj`| -|||An immutable, fixed-length string of Unicode characters.|`String`|`string`|`String^`|`string`| - -In addition to the base data types, the namespace contains over 100 classes, ranging from classes that handle exceptions to classes that deal with core runtime concepts, such as application domains and the garbage collector. The namespace also contains many second-level namespaces. - -For more information about namespaces, use the [.NET API Browser](../../api/index.md) to browse the .NET Class Library. The API reference documentation provides documentation on each namespace, its types, and each of their members. +The namespace is the root namespace for fundamental types in .NET. This namespace includes classes that represent the base data types used by all applications, for example, (the root of the inheritance hierarchy), , , , , and . + +Many of these types correspond to the primitive data types that a programming language uses. When you write code using .NET types, you can use the corresponding language keyword when a .NET base data type is expected. For more information, see: + +- [Built-in types (C# reference)](../csharp/language-reference/builtin-types/built-in-types.md) +- [Primitive types (Visual Basic)](/dotnet/visual-basic/reference/language-specification/types#primitive-types) +- [Basic types (F#)](../fsharp/language-reference/basic-types.md) + +In addition to the base data types, the namespace contains over 100 classes, ranging from classes that handle exceptions to classes that deal with core runtime concepts, such as garbage collection. The namespace also contains many second-level namespaces. + +The [.NET API reference documentation](../../api/index.md) provides documentation on each namespace, its types, and their members. ## Data structures .NET includes a set of data structures that are the workhorses of many .NET apps. These are mostly collections, but also include other types. -* - Represents an array of strongly typed objects that can be accessed by index. Has a fixed size, per its construction. -* - Represents a strongly typed list of objects that can be accessed by index. Is automatically resized as needed. -* - Represents a collection of values that are indexed by a key. Values can be accessed via key. Is automatically resized as needed. -* - Provides an object representation of a uniform resource identifier (URI) and easy access to the parts of the URI. -* - Represents an instant in time, typically expressed as a date and time of day. +- - Represents an array of strongly typed objects that can be accessed by index. Has a fixed size, per its construction. +- - Represents a strongly typed list of objects that can be accessed by index. Is automatically resized as needed. +- - Represents a collection of values that are indexed by a key. Values can be accessed via key. Is automatically resized as needed. +- - Provides an object representation of a uniform resource identifier (URI) and easy access to the parts of the URI. +- - Represents an instant in time, typically expressed as a date and time of day. ## Utility APIs .NET includes a set of utility APIs that provide functionality for many important tasks. -* - An API for sending HTTP requests and receiving HTTP responses from a resource identified by a URI. -* - An API for loading and querying XML documents with LINQ. -* - An API for reading files. -* - An API for writing files. +- - An API for sending HTTP requests and receiving HTTP responses from a resource identified by a URI. +- and : An API for writing logging and debugging information during application execution. +- and - APIs for reading and writing files. +- - An API for serializing objects or value types to JSON and deserializing JSON into objects or value types. ## App-model APIs There are many app models that can be used with .NET, for example: -* [ASP.NET](https://dotnet.microsoft.com/apps/aspnet) - A web framework for building web sites and services. Supported on Windows, Linux, and macOS (depends on ASP.NET version). -* [.NET MAUI](https://dotnet.microsoft.com/apps/maui) - An app platform for building native apps that run on Windows, macOS, iOS, and Android using C#. -* [Windows Desktop](https://www.nuget.org/packages/Microsoft.WindowsDesktop.App.Ref/) - Includes Windows Presentation Foundation (WPF) and Windows Forms. +- [ASP.NET Core](https://dotnet.microsoft.com/apps/aspnet) - A web framework for building web sites and services. Supported on Windows, Linux, and macOS. +- [.NET MAUI](https://dotnet.microsoft.com/apps/maui) - An app platform for building native apps that run on Windows, macOS, iOS, and Android using C#. +- [Windows Desktop](https://www.nuget.org/packages/Microsoft.WindowsDesktop.App.Ref/) - Includes Windows Presentation Foundation (WPF) and Windows Forms. ## See also diff --git a/docs/standard/runtime-libraries-overview.md b/docs/standard/runtime-libraries-overview.md index 1230de6cbc559..42b69d05b4c2b 100644 --- a/docs/standard/runtime-libraries-overview.md +++ b/docs/standard/runtime-libraries-overview.md @@ -1,7 +1,7 @@ --- title: Runtime libraries overview description: Learn what is included in the Runtime libraries section of the table of contents. -ms.date: 05/30/2024 +ms.date: 11/05/2025 --- # Runtime libraries overview @@ -19,16 +19,18 @@ Some libraries are provided in NuGet packages rather than as part of the runtime The following table shows some examples of package-provided libraries. -| NuGet package | Conceptual content | -|-------------------------------------------------------|--------------------------------------------------------------------| -| [`Microsoft.Extensions.Configuration`][configuration] | [Configuration](../core/extensions/configuration.md) | -| [`Microsoft.Extensions.DependencyInjection`][di] | [Dependency injection](../core/extensions/dependency-injection.md) | -| [`Microsoft.Extensions.FileSystemGlobbing`][fsg] | [File globbing](../core/extensions/file-globbing.md) | -| [`Microsoft.Extensions.Hosting`][host] | [Generic Host](../core/extensions/generic-host.md) | -| [`Microsoft.Extensions.Http`][http] | [HTTP](../core/extensions/httpclient-factory.md) | -| [`Microsoft.Extensions.Localization`][loc] | [Localization](../core/extensions/localization.md) | -| [`Microsoft.Extensions.Logging`][log] | [Logging](../core/extensions/logging.md) | - +| NuGet package | Conceptual content | +|---------------------------------|----------------------------------------| +| [`Microsoft.Extensions.AI`][ai] | [AI](../ai/microsoft-extensions-ai.md) | +| [`Microsoft.Extensions.Configuration`][configuration] | [Configuration](../core/extensions/configuration.md) | +| [`Microsoft.Extensions.DependencyInjection`][di] | [Dependency injection](../core/extensions/dependency-injection.md) | +| [`Microsoft.Extensions.FileSystemGlobbing`][fsg] | [File globbing](../core/extensions/file-globbing.md) | +| [`Microsoft.Extensions.Hosting`][host] | [Generic Host](../core/extensions/generic-host.md) | +| [`Microsoft.Extensions.Http`][http] | [HTTP](../core/extensions/httpclient-factory.md) | +| [`Microsoft.Extensions.Localization`][loc] | [Localization](../core/extensions/localization.md) | +| [`Microsoft.Extensions.Logging`][log] | [Logging](../core/extensions/logging.md) | + +[ai]: https://www.nuget.org/packages/Microsoft.Extensions.AI [configuration]: https://www.nuget.org/packages/Microsoft.Extensions.Configuration [di]: https://www.nuget.org/packages/Microsoft.Extensions.DependencyInjection [fsg]: https://www.nuget.org/packages/Microsoft.Extensions.FileSystemGlobbing diff --git a/docs/standard/serialization/system-text-json/nullable-annotations.md b/docs/standard/serialization/system-text-json/nullable-annotations.md index 8a5f7d65f44ad..06193824a24c8 100644 --- a/docs/standard/serialization/system-text-json/nullable-annotations.md +++ b/docs/standard/serialization/system-text-json/nullable-annotations.md @@ -1,8 +1,9 @@ --- title: Respect nullable annotations description: "Learn how to configure serialization and deserialization to respect nullable annotations." -ms.date: 10/22/2024 +ms.date: 10/20/2025 no-loc: [System.Text.Json, Newtonsoft.Json] +ai-usage: ai-assisted --- # Respect nullable annotations @@ -84,6 +85,21 @@ record MyPoco( ); ``` +## Missing values versus null values + +It's important to understand the distinction between *missing JSON properties* and *properties with explicit `null` values* when you set . JavaScript distinguishes between `undefined` (missing property) and `null` (explicit null value). However, .NET doesn't have an `undefined` concept, so both cases deserialize to `null` in .NET. + +During deserialization, when `RespectNullableAnnotations` is `true`: + +- An **explicit null value** throws an exception for non-nullable properties. For example, `{"Name":null}` throws an exception when deserializing to a non-nullable `string Name` property. +- A **missing property** doesn't throw an exception, even for non-nullable properties. For example, `{}` doesn't throw an exception when deserializing to a non-nullable `string Name` property. The serializer doesn't set the property, leaving it at its default value from the constructor. For an uninitialized non-nullable reference type, this results in `null`, which triggers a compiler warning. + + The following code shows how a missing property does NOT throw an exception during deserialization: + + :::code language="csharp" source="snippets/nullable-annotations/Nullable.cs" id="MissingVsNull"::: + +This behavior difference occurs because missing properties are treated as optional (not provided), while explicit `null` values are treated as provided values that violate the non-nullable constraint. If you need to enforce that a property must be present in the JSON, use the `required` modifier or configure the property as required using or the contracts model. + ## See also - [Non-optional constructor parameters](required-properties.md#non-optional-constructor-parameters) diff --git a/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Nullable.cs b/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Nullable.cs index 99cbf61b9a71f..86c2fc086f4de 100644 --- a/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Nullable.cs +++ b/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Nullable.cs @@ -58,3 +58,24 @@ record Person(string Name); // } +public static class Nullable4 +{ + // + public static void RunIt() + { +#nullable enable + JsonSerializerOptions options = new() + { + RespectNullableAnnotations = true + }; + + // Missing property - does NOT throw an exception. + string jsonMissing = """{}"""; + var resultMissing = JsonSerializer.Deserialize(jsonMissing, options); + Console.WriteLine(resultMissing.Name is null); // True. + } + + record Person(string Name); + // +} + diff --git a/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Program.cs b/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Program.cs index 816681470e389..82413ada4b464 100644 --- a/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Program.cs +++ b/docs/standard/serialization/system-text-json/snippets/nullable-annotations/Program.cs @@ -1,3 +1,4 @@ //Nullable1.RunIt(); //Nullable2.RunIt(); -Nullable3.RunIt(); +//Nullable3.RunIt(); +Nullable4.RunIt(); diff --git a/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md b/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md index 20c007be36897..090f8a47ad0b9 100644 --- a/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md +++ b/docs/visual-basic/developing-apps/programming/drives-directories-files/classes-used-in-net-framework-file-io-and-the-file-system.md @@ -2,62 +2,61 @@ description: "Learn more about: Classes Used in .NET Framework File I/O and the File System (Visual Basic)" title: "Classes Used in .NET Framework File I/O and the File System" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "file I/O classes" ms.assetid: 4a5ca924-eea8-4a95-a5f0-6ac10de276a3 --- # Classes Used in .NET Framework File I/O and the File System (Visual Basic) -The following tables list the classes commonly used for .NET Framework file I/O, categorized into file I/O classes, classes used for creating streams, and classes used to read and write to streams. - -For a more comprehensive listing, see [Class Library Overview](../../../../standard/class-library-overview.md). - -## Basic I/O Classes for Files, Drives, and Directories - - The following table lists and describes the main classes used for file I/O. - -|Class|Description| -|-----------|-----------------| -||Provides static methods for creating, moving, and enumerating through directories and subdirectories.| -||Provides instance methods for creating, moving, and enumerating through directories and subdirectories.| -||Provides instance methods for creating, moving, and enumerating through drives.| -||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| -||Defines constants for read, write, or read/write access to a file.| -||Provides attributes for files and directories such as `Archive`, `Hidden`, and `ReadOnly`.| -||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| -||Controls how a file is opened. This parameter is specified in many of the constructors for `FileStream` and `IsolatedStorageFileStream`, and for the `Open` methods of and .| -||Defines constants for controlling the type of access other file streams can have to the same file.| -||Provides methods and properties for processing directory strings.| -||Controls the access of files and folders by defining , , and permissions.| - -## Classes Used to Create Streams - - The following table lists and describes the main classes used to create streams. - -|Class|Description| -|-----------|-----------------| -||Adds a buffering layer to read and write operations on another stream.| -||Supports random access to files through its method. opens files synchronously by default but also supports asynchronous operation.| -||Creates a stream whose backing store is memory, rather than a file.| -||Provides the underlying stream of data for network access.| -||Defines a stream that links data streams to cryptographic transformations.| - -## Classes Used to Read from and Write to Streams - - The following table shows the specific classes used for reading from and writing to files with streams. - -|**Class**|**Description**| -|---------------|---------------------| -||Reads encoded strings and primitive data types from a .| -||Writes encoded strings and primitive data types to a .| -||Reads characters from a , using to convert characters to and from bytes. has a constructor that attempts to ascertain the correct for a given stream, based on the presence of a -specific preamble, such as a byte order mark.| -||Writes characters to a `FileStream`, using to convert characters to bytes.| -||Reads characters from a `String`. Output can be either a stream in any encoding or a `String`.| -||Writes characters to a `String`. Output can be either a stream in any encoding or a `String`.| - +The following tables list the classes commonly used for .NET Framework file I/O, categorized into file I/O classes, classes used for creating streams, and classes used to read and write to streams. + +## Basic I/O Classes for Files, Drives, and Directories + + The following table lists and describes the main classes used for file I/O. + +|Class|Description| +|-----------|-----------------| +||Provides static methods for creating, moving, and enumerating through directories and subdirectories.| +||Provides instance methods for creating, moving, and enumerating through directories and subdirectories.| +||Provides instance methods for creating, moving, and enumerating through drives.| +||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| +||Defines constants for read, write, or read/write access to a file.| +||Provides attributes for files and directories such as `Archive`, `Hidden`, and `ReadOnly`.| +||Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of a `FileStream`.| +||Controls how a file is opened. This parameter is specified in many of the constructors for `FileStream` and `IsolatedStorageFileStream`, and for the `Open` methods of and .| +||Defines constants for controlling the type of access other file streams can have to the same file.| +||Provides methods and properties for processing directory strings.| +||Controls the access of files and folders by defining , , and permissions.| + +## Classes Used to Create Streams + + The following table lists and describes the main classes used to create streams. + +|Class|Description| +|-----------|-----------------| +||Adds a buffering layer to read and write operations on another stream.| +||Supports random access to files through its method. opens files synchronously by default but also supports asynchronous operation.| +||Creates a stream whose backing store is memory, rather than a file.| +||Provides the underlying stream of data for network access.| +||Defines a stream that links data streams to cryptographic transformations.| + +## Classes Used to Read from and Write to Streams + + The following table shows the specific classes used for reading from and writing to files with streams. + +|**Class**|**Description**| +|---------------|---------------------| +||Reads encoded strings and primitive data types from a .| +||Writes encoded strings and primitive data types to a .| +||Reads characters from a , using to convert characters to and from bytes. has a constructor that attempts to ascertain the correct for a given stream, based on the presence of a -specific preamble, such as a byte order mark.| +||Writes characters to a `FileStream`, using to convert characters to bytes.| +||Reads characters from a `String`. Output can be either a stream in any encoding or a `String`.| +||Writes characters to a `String`. Output can be either a stream in any encoding or a `String`.| + ## See also - [Composing Streams](../../../../standard/io/composing-streams.md) - [File and Stream I/O](../../../../standard/io/index.md) - [Asynchronous File I/O](../../../../standard/io/asynchronous-file-i-o.md) - [Basics of .NET Framework File I/O and the File System (Visual Basic)](basics-of-net-framework-file-io-and-the-file-system.md) +- [Core .NET libraries overview](../../../../standard/class-library-overview.md) diff --git a/docs/visual-basic/reference/net-framework-reference-information.md b/docs/visual-basic/reference/net-framework-reference-information.md index bd46906deb022..88b50a81a39b5 100644 --- a/docs/visual-basic/reference/net-framework-reference-information.md +++ b/docs/visual-basic/reference/net-framework-reference-information.md @@ -2,7 +2,7 @@ description: "Learn more about: .NET Framework Reference Information (Visual Basic)" title: ".NET Framework Reference Information" ms.date: 07/20/2015 -helpviewer_keywords: +helpviewer_keywords: - "language reference [Visual Basic], .NET Framework" - ".NET Framework [Visual Basic], reference" - ".NET Framework class library [Visual Basic], reference information" @@ -10,21 +10,21 @@ ms.assetid: 8b202505-608b-4223-bbd9-2ace3d73e6cd --- # .NET Framework Reference Information (Visual Basic) -This topic provides links to information about how to work with the .NET Framework class library. - -## Related Sections +This topic provides links to information about how to work with the .NET Framework class library. - [Getting Started](../../framework/get-started/index.md) - Provides a comprehensive overview of the .NET Framework and links to additional resources. - - [Class Library Overview](../../standard/class-library-overview.md) - Introduces the classes, interfaces, and value types that help expedite and optimize the development process and provide access to system functionality. - - [Development Guide](../../framework/development-guide.md) - Provides a guide to all key technology areas and tasks for application development, including creating, configuring, debugging, securing, and deploying your application. This topic also provides information about dynamic programming, interoperability, extensibility, memory management, and threading. - - [Tools](../../framework/tools/index.md) - Describes the tools that you can use to develop, configure, and deploy applications by using .NET Framework technologies. - - [.NET API Browser](../../../api/index.md) +## Related Sections + + [Getting Started](../../framework/get-started/index.md)\ + Provides a comprehensive overview of the .NET Framework and links to additional resources. + + [Core .NET Libraries Overview](../../standard/class-library-overview.md)\ + Introduces the classes, interfaces, and value types that help expedite and optimize the development process and provide access to system functionality. + + [Development Guide](../../framework/development-guide.md)\ + Provides a guide to all key technology areas and tasks for application development, including creating, configuring, debugging, securing, and deploying your application. This topic also provides information about dynamic programming, interoperability, extensibility, memory management, and threading. + + [Tools](../../framework/tools/index.md)\ + Describes the tools that you can use to develop, configure, and deploy applications by using .NET Framework technologies. + + [.NET API Browser](../../../api/index.md)\ Provides syntax, code examples, and related information for each class in the .NET Framework namespaces.